Payouts

Send money to a seller's Nigerian bank account, for example when you settle a marketplace order.

Create a payout

POST/v1/payouts

Field	Type	Notes
`reference`	string, required	Your unique id for this payout.
`amount`	integer, required	Kobo. Minimum 10,000 (₦100). Maximum 2,000,000,000.
`currency`	string, required	Always "NGN".
`recipient.bankName`	string, required	For example "Access Bank". Payder matches it to a Nigerian bank.
`recipient.accountNumber`	string, required	10-digit NUBAN account number.
`recipient.accountName`	string, required	The account holder's name.
`narration`	string	Up to 100 characters.

bash

curl -s $BASE/v1/payouts \
  -H "Authorization: Bearer $KEY" -H "X-Merchant-Id: $MID" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{
    "reference": "PO-77",
    "amount": 5000000,
    "currency": "NGN",
    "recipient": {
      "bankName": "Access Bank",
      "accountNumber": "0123456789",
      "accountName": "Seller One"
    },
    "narration": "Marketplace payout"
  }'

Response 201

{ "id": "pyo_7d1e...", "reference": "PO-77", "status": "pending" }

A payout starts as pending and ends as succeeded or failed, announced by payout.succeeded or payout.failed.

Retrieve a payout

GET/v1/payouts/:reference

Rules

The account number must be exactly 10 digits, or you get 400 invalid_request. A bank name Payder cannot match returns 422 unsupported_bank.
Live: a payout cannot exceed your available balance, which is what buyers have paid you minus refunds and earlier payouts. Otherwise: 422 insufficient_balance.
A failed payout returns its amount to your available balance.
Live payouts can take longer than sandbox ones. Some are reviewed by Payder before they are sent, so always wait for the webhook rather than assuming instant settlement.

Sandbox test accounts: 0123456789 succeeds, 0000000000 fails. Any other 10-digit number succeeds. See Sandbox and testing.

← Refunds Escrow →