> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedemat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API basics

> Base URL, environments, request format, response envelope, and money units.

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](/guides/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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer sk_test_your_secret_key
Content-Type: application/json
```

`POST` routes that create or move money also require `Idempotency-Key`. See [Idempotency](/guides/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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "A human readable explanation",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}
```

See [Errors](/guides/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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.