Create a checkout session

Start hosted checkout. Pass escrowId XOR customerId. EscrowId funds an awaiting_funding hold (amount and currency must match). A second POST for that same unfunded hold returns the existing pending session. It does not start another charge. Same Idempotency-Key + same body replays the first response. Different key + same escrowId still returns that pending session. CustomerId credits that customer’s available and does not lock a hold; wallet top-ups may have more than one open session. PaymentMethods, if omitted, uses the channels enabled on your Demat dashboard (card only until you turn others on). See Callback URL. Webhook: payment.pending.

POST

checkout

sessions

Error

A valid request URL is required to generate request examples

{
  "success": true,
  "data": {
    "checkoutId": "chk_01hxyz",
    "status": "pending",
    "paymentId": "pay_01hxyz",
    "customerId": "cus_01hxyz",
    "provider": "<string>",
    "amount": 400,
    "chargedAmount": 407.5,
    "netAmount": 400,
    "fees": {
      "providerFee": 6,
      "platformFee": 1.5,
      "merchantFee": 0,
      "totalFees": 7.5
    },
    "checkoutUrl": "https://checkout.example.com/abc",
    "escrowId": "esc_01hxyz",
    "walletId": "wal_01hxyz"
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

Authorizations

Authorization

string

header

required

Secret API key. Use sk_test_... for sandbox data or sk_live_... for live data (after verification and live mode). Do not use pk_ keys.

Headers

Idempotency-Key

string

required

Body

application/json

escrowId or customerId (not both), amount in naira, currency, optional paymentMethods, and optional callbackUrl.

amount

number

required

Charge amount in naira. Must match the escrow when funding one.

Example:

400

currency

string

required

ISO currency code. Must match the escrow or wallet.

Example:

"NGN"

escrowId

string

Escrow to fund. Provide this or customerId, not both.

Example:

"esc_01hxyz"

customerId

string

Customer whose wallet to credit. Provide this or escrowId, not both.

Example:

"cus_01hxyz"

paymentMethods

enum<string>[]

Checkout channels for this session. Allowed: card, bank, bank_transfer, ussd. If omitted, the channels enabled on your Demat dashboard are used (card only until you turn others on).

Available options:

card,

bank,

bank_transfer,

ussd

Example:

["card", "bank_transfer"]

callbackUrl

string

Browser return URL after checkout. Must be https with a public domain. If omitted, the merchant account callbackUrl is used. If that is also empty, we send no default so the payer is not sent to a Demat page.

Example:

"https://yourapp.com/payments/callback"

Response

Resource created

success

boolean

Example:

true

data

object

Show child attributes

meta

object

Show child attributes

Error

A valid request URL is required to generate request examples

{
  "success": true,
  "data": {
    "checkoutId": "chk_01hxyz",
    "status": "pending",
    "paymentId": "pay_01hxyz",
    "customerId": "cus_01hxyz",
    "provider": "<string>",
    "amount": 400,
    "chargedAmount": 407.5,
    "netAmount": 400,
    "fees": {
      "providerFee": 6,
      "platformFee": 1.5,
      "merchantFee": 0,
      "totalFees": 7.5
    },
    "checkoutUrl": "https://checkout.example.com/abc",
    "escrowId": "esc_01hxyz",
    "walletId": "wal_01hxyz"
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

customers

escrows

checkout

transactions

wallets

payouts

fees

identity

Create a checkout session

Authorizations

Headers

Body

Response