Every endpoint on one page. The full machine-readable contract is the OpenAPI file.
Download openapi.yaml and import it into Postman, Insomnia or a code generator.
Base URLs: https://sandbox-api.payder.ng (sandbox) and https://api.payder.ng (live). Send Authorization and X-Merchant-Id on every request, and Idempotency-Key on every POST.
Endpoints
| Method | Path | Success | Guide |
|---|
| POST | /v1/checkouts | 201 {id, reference, checkoutUrl, status} | Accept payments |
| GET | /v1/checkouts/:reference | 200 checkout | Accept payments |
| POST | /v1/refunds | 201 {id, reference, status} | Refunds |
| GET | /v1/refunds/:reference | 200 refund | Refunds |
| POST | /v1/payouts | 201 {id, reference, status} | Payouts |
| GET | /v1/payouts/:reference | 200 payout | Payouts |
| POST | /v1/escrows | 201 {id, reference, payUrl, status} | Escrow |
| GET | /v1/escrows/:reference | 200 escrow | Escrow |
| POST | /v1/escrows/:reference/release | refund | cancel | 200 escrow | Escrow |
| GET | /v1/accounts/:walletId | 200 {exists, name} | Escrow |
| GET | /v1/banks | 200 {data:[{name, code}]} | Payouts |
| GET | /v1/balance | 200 {paidInMinor, availableMinor, …} | Payouts |
Objects
Checkout
| Field | Type |
|---|
id | string |
reference | string |
status | pending | succeeded | failed |
amount | integer (kobo) |
currency | "NGN" |
description | string | null |
customer.email | string |
metadata | object | null |
checkoutUrl | string |
paymentMethod | string | null |
failureReason | string | null |
refundedAmount | integer (kobo) |
paidAt | ISO 8601 | null |
createdAt | ISO 8601 |
Refund
| Field | Type |
|---|
id | string |
reference | string |
status | pending | succeeded | failed |
paymentReference | string |
amount | integer (kobo) |
currency | "NGN" |
reason | string | null |
failureReason | string | null |
createdAt | ISO 8601 |
Payout
| Field | Type |
|---|
id | string |
reference | string |
status | pending | succeeded | failed |
amount | integer (kobo) |
currency | "NGN" |
recipient | { bankName, accountNumber, accountName } |
narration | string | null |
failureReason | string | null |
createdAt | ISO 8601 |
Webhook event
| Field | Type |
|---|
event | payment.succeeded | payment.failed | refund.succeeded | refund.failed | payout.succeeded | payout.failed |
reference | string (your reference) |
amountMinor | integer (kobo) |
currency | "NGN" |
occurredAt | ISO 8601 |
Object field lists can grow over time. Ignore fields you do not recognise rather than failing on them.