API basics

The Escrow API is a RESTful JSON API. Most routes require authentication. Use it to create customers, take checkout payments, lock money in a hold, release or refund that hold, and send payouts to a bank. All requests must be made over HTTPS. Unencrypted HTTP is not supported in production.

Base URL

https://prod.demat.shop/api/v1

Use this same base URL for test and live. Test vs live is selected by your secret key, not by changing the host. A test key (sk_test_) always uses sandbox data. A live key (sk_live_) uses live data and requires a verified merchant account that has been switched to live mode.

Environments and API keys

Each merchant has test and live keys. The key selects the data plane (sandbox vs live).

Environment	Secret key	Publishable key	When to use
Test	`sk_test_`	`pk_test_`	Integration work. Sandbox data and dummy providers.
Live	`sk_live_`	`pk_live_`	Production. Requires a verified account in live mode.

Publishable keys (pk_) are for client side checkout. Never send a pk_ key as a Bearer token. See Authentication.

HTTP methods

Method	Description
`GET`	Retrieve a resource or a list.
`POST`	Create a resource or perform an action (release, refund, payout).
`PATCH`	Update a resource (for example `PATCH /customers/{id}`).
`DELETE`	Remove a resource (for example `DELETE /customers/{id}`).

Making requests

Send JSON and include your secret key:

Authorization: Bearer sk_test_your_secret_key
Content-Type: application/json

POST routes that create or move money also require Idempotency-Key. See Idempotency.

Requests and responses

Request and response bodies are JSON. Field names are camelCase (requestId, customerId, limit, offset), not snake_case. Successful responses use this envelope:

{
  "success": true,
  "data": {},
  "meta": {
    "requestId": "req_01hxyz"
  }
}

Field	Type	Description
`success`	boolean	`true` when the request was processed as intended. Combine this with the HTTP status code.
`data`	object	Result of the call. A fetch returns the resource. A list returns a named array of records (for example `customers`) plus a `pagination` object.
`meta.requestId`	string	Correlate logs and support requests. Echoed from `X-Request-Id` when you send one.

Failed requests use:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "A human readable explanation",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

See Errors.

Money

Amounts are integers in naira. Send 200 for ₦200. Do not send kobo. Two customer balances matter:

Balance	Meaning
`available`	The customer can withdraw this, or you can lock it with `debitPayer: true`.
`held`	Locked on one or more open escrows. Not withdrawable until released or refunded.

Release does not send money to a bank. It credits the payee’s available. A bank payout is POST /withdrawals.

Get started

Integrations

API basics

Base URL

Environments and API keys

HTTP methods

Making requests

Requests and responses

Money

​Base URL

​Environments and API keys

​HTTP methods

​Making requests

​Requests and responses

​Money

Base URL

Environments and API keys

HTTP methods

Making requests

Requests and responses

Money