Accept payments

A checkout is one payment attempt for one order. You create it on your server, then send the buyer to its hosted payment page.

Create a checkout

POST/v1/checkouts

Field	Type	Notes
`reference`	string, required	Your unique id for this payment, usually the order number. Up to 100 characters: letters, digits and . _ : -
`amount`	integer, required	In kobo. Minimum 100 (₦1). Maximum 2,000,000,000 (₦20,000,000).
`currency`	string, required	Always "NGN".
`description`	string	Shown to the buyer on the payment page. Up to 255 characters.
`customer.email`	string, required	The buyer's email.
`returnUrl`	string, required	Where the buyer lands afterwards. Must be https in live.
`metadata`	object	Anything you want back later, such as {"orderCode":"Q-1001"}. Up to 4 KB.

Response 201

{
  "id": "chk_9f2c...",
  "reference": "ORD-1001",
  "checkoutUrl": "https://www.payder.ng/pay/chk_9f2c...",
  "status": "pending"
}

A repeated reference is rejected with 409 duplicate_reference, unless it is an idempotent replay of the same request (same Idempotency-Key and body), which returns the original checkout.

Send the buyer to checkoutUrl

The hosted page lets the buyer pay by card or bank transfer. When they finish, Payder redirects them to your returnUrl with two query parameters added: reference and status (succeeded, failed or pending).

Never trust the redirect

A buyer can open your return URL by hand with status=succeeded. Treat the redirect only as a cue to show a result page, and confirm the real status from the webhook or with GET /v1/checkouts/:reference before you ship goods.

Retrieve a checkout

GET/v1/checkouts/:reference

Response 200

{
  "id": "chk_9f2c...",
  "reference": "ORD-1001",
  "status": "succeeded",
  "amount": 1250000,
  "currency": "NGN",
  "description": "Order Q-1001",
  "customer": { "email": "buyer@example.com" },
  "metadata": { "orderCode": "Q-1001" },
  "checkoutUrl": "https://www.payder.ng/pay/chk_9f2c...",
  "paymentMethod": "card",
  "failureReason": null,
  "refundedAmount": 0,
  "paidAt": "2026-10-04T18:02:11.000Z",
  "createdAt": "2026-10-04T18:00:03.000Z"
}

Statuses

Status	Meaning
`pending`	Created and waiting for the buyer, or the payment is still being confirmed.
`succeeded`	Paid. You will receive payment.succeeded. Refunds are now possible.
`failed`	The payment failed or the link expired. failureReason says why. You will receive payment.failed.

A checkout that is not paid within 24 hours expires and becomes failed with the reason expired. To let the buyer try again, create a new checkout with a new reference.

Tips

Create the checkout when the buyer clicks Pay, not when they add to cart.
Use your order number as reference, so you can always look a payment up from your own records.
Verify that amountMinor in the webhook equals what you expected before you mark an order paid.

← Authentication Refunds →