Checkout

A checkout is a payment your customer completes on a MigraPay payment page: you set the price, they choose the currency and method. For how to put it on your site, see the Checkout guide and the checkout.js reference.

Payment methods

Only currencies that are enabled for collections on your account are offered. The customer sees the total in each currency before choosing; the amount shown includes all fees.

Create a checkout

POST /checkout requires the collection.create scope and supports Idempotency-Key: retrying with the same key returns the same checkout.

curl -X POST https://business-api.migrapay.com/v1/api/checkout \
  -H "Authorization: Bearer $MIGRAPAY_API_KEY" \
  -H "Idempotency-Key: ORDER-1048" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "NGN",
    "currencies": ["NGN", "CAD"],
    "reference": "1048",
    "description": "Naija Market Day order",
    "customer": { "email": "[email protected]", "name": "Ada Okafor" },
    "redirectUrl": "https://your-site.com/orders/1048",
    "metadata": { "orderId": 1048 }
  }'

{
  "status": "success",
  "message": "Checkout created successfully.",
  "data": {
    "id": "9683e7b6-532a-4a5b-9c51-ee404b960f24",
    "token": "pr_d78890ba7b7a49fb97f3228f8008c3ad",
    "checkoutUrl": "https://migrapay.com/checkout/pr_d78890ba7b7a49fb97f3228f8008c3ad",
    "status": "awaiting_payment",
    "amount": 25000,
    "currency": "NGN",
    "expiresAt": "2026-11-04T07:51:57.256Z"
  }
}

Keep id: it is how you confirm the payment and how webhooks refer to it (requestId).

Retrieve a checkout

GET /checkout/{id} returns the checkout as a collection object: its status, the amounts, payer, funding, metadata and history. Requires collection.view.

curl https://business-api.migrapay.com/v1/api/checkout/9683e7b6-532a-4a5b-9c51-ee404b960f24 \
  -H "Authorization: Bearer $MIGRAPAY_API_KEY"

Fulfil the order when status is settled. If the customer paid in another currency than your price, currency and amount are what they paid; your original price is on the webhook as checkout.base. Unknown ids return 404 REQUEST_NOT_FOUND.

Start a checkout with a public key

POST /v1/checkout/sessions starts a checkout from your website or app. It is authenticated by your public key in the X-MigraPay-Key header, not by your secret key, and is not under /api. A pk_test_ key starts a Sandbox checkout.

curl -X POST https://business-api.migrapay.com/v1/checkout/sessions \
  -H "X-MigraPay-Key: pk_live_9sK2mQ7xLp4Rt8VwYc3Nb6Hd" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25000, "currency": "NGN", "reference": "ORDER-1048",
       "customer": {"email": "[email protected]", "name": "Ada Okafor"}}'

{
  "status": "success",
  "message": "Checkout created successfully.",
  "data": {
    "token": "pr_d78890ba7b7a49fb97f3228f8008c3ad",
    "checkoutUrl": "https://migrapay.com/checkout/pr_d78890ba7b7a49fb97f3228f8008c3ad"
  }
}

Open token with checkout.js or send the customer to checkoutUrl.

Errors: 401 INVALID_PUBLIC_KEY (missing, unknown or rotated key), 403 ORIGIN_NOT_ALLOWED (the calling site is not in the key's allowed websites), 400 VALIDATION_ERROR, 429 when called too often (30 a minute).

Read checkout options

GET /v1/checkout/config with the same X-MigraPay-Key header returns your business's display name, the currencies and methods a checkout can offer, and the key's mode. Use it to build your own payment picker.

{
  "status": "success",
  "message": "Checkout config retrieved successfully.",
  "data": {
    "merchantName": "Acme Ltd",
    "currencies": [
      { "currency": "NGN", "methods": ["card", "bank_transfer", "ussd"] },
      { "currency": "CAD", "methods": ["interac"] }
    ],
    "mode": "live"
  }
}

mode is live or sandbox. Errors are the same as for sessions; it allows 60 calls a minute.

Lifecycle

1. awaiting_paymentCheckout open; waiting for the customer.
2. processingPayment received and being confirmed.
3. settledFunds credited to your wallet. collection.settled fires.
4. expiredNot paid in time. collection.expired fires.
5. refundedReturned to the payer after settling. collection.refunded fires.

Test cards

Any name and any future expiry date work in Sandbox; keep amounts small on the test environment (for example NGN 100), where larger test charges may be declined.

When a card needs bank verification, the checkout shows the bank's one-time-password step in the same window; enter the OTP and the checkout continues to the receipt. Any other card number is declined.