Create an escrow

Create a hold with one payer and one payee. Payer may be a registered customerId or a guest { email, name?, phone? }. Payee must be a registered customerId. Your reference must be unique. Default status is awaiting_funding. No money is locked. Pass checkout true to also return a checkout URL. Pass debitPayer true only for registered payers with available ≥ amount; not allowed for guests. A NUBAN credit never locks this hold. Webhook: escrow.created, then escrow.funded if debitPayer succeeded.

POST

escrows

Error

A valid request URL is required to generate request examples

{
  "success": true,
  "data": {
    "escrowId": "esc_01hxyz",
    "reference": "order_12345",
    "status": "awaiting_funding",
    "amount": 400,
    "currency": "NGN",
    "releasedAmount": 0,
    "refundedAmount": 0,
    "remainingAmount": 400,
    "feeAmount": 107.5,
    "merchantFee": 100,
    "parties": [
      {
        "customerId": "cus_01hxyz",
        "role": "payer",
        "guest": {
          "email": "[email protected]",
          "name": "John Doe",
          "phone": "+2348012345678"
        }
      }
    ],
    "description": "<string>",
    "cancelledReason": "<string>",
    "fundedAt": null,
    "releasedAt": null,
    "refundedAt": null,
    "pendingProviderRefund": null,
    "checkout": {
      "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"
  }
}

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

reference, amount in naira, currency, parties (one payer and one payee; payer may use guest), optional debitPayer, optional checkout, and optional description.

reference

string

required

Your unique reference. Duplicate values are rejected.

Example:

"order_12345"

amount

number

required

Agreed hold amount in naira. 400 = ₦400.

Example:

400

currency

string

required

ISO currency code.

Example:

"NGN"

parties

object[]

required

Must include one payer and one payee. Payer may be a registered customerId or a guest object. Payee must be a registered customerId.

Show child attributes

description

string

Short note shown on the escrow and in webhooks.

merchantFee

number

Optional merchant surcharge in naira. Added on top of provider and Demat fees at checkout. Credited to your settlement balance when funding completes.

Example:

0

debitPayer

boolean

If true, debit the payer's available balance now. The payer must be a registered customer with a wallet and available balance of at least amount, otherwise the request fails. Not allowed for guest payers. Default false: the hold is created as awaiting_funding. Cannot be combined with checkout.

Example:

false

checkout

boolean

If true, start hosted checkout for this hold and return the checkout session on the create response. Only when the hold is awaiting_funding. Cannot be combined with debitPayer. Omit to create the hold only. You can still POST /checkout/sessions later.

Example:

true

paymentMethods

enum<string>[]

Checkout channels when checkout is true. Allowed: card, bank, bank_transfer, ussd. If omitted, the channels enabled on your Demat dashboard are used (card only until you turn others on). Ignored unless checkout is true.

Available options:

card,

bank,

bank_transfer,

ussd

Example:

["card", "bank_transfer"]

callbackUrl

string

Browser return URL after checkout when checkout is true. Must be https with a public domain. If omitted, the merchant account callbackUrl is used. Ignored unless checkout is true.

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": {
    "escrowId": "esc_01hxyz",
    "reference": "order_12345",
    "status": "awaiting_funding",
    "amount": 400,
    "currency": "NGN",
    "releasedAmount": 0,
    "refundedAmount": 0,
    "remainingAmount": 400,
    "feeAmount": 107.5,
    "merchantFee": 100,
    "parties": [
      {
        "customerId": "cus_01hxyz",
        "role": "payer",
        "guest": {
          "email": "[email protected]",
          "name": "John Doe",
          "phone": "+2348012345678"
        }
      }
    ],
    "description": "<string>",
    "cancelledReason": "<string>",
    "fundedAt": null,
    "releasedAt": null,
    "refundedAt": null,
    "pendingProviderRefund": null,
    "checkout": {
      "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"
  }
}

customers

escrows

checkout

transactions

wallets

payouts

fees

identity

Create an escrow

Authorizations

Headers

Body

Response