> For the complete documentation index, see [llms.txt](https://docs.makapay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.makapay.io/developers/api-reference.md).

# API Reference

Complete API documentation for integrating MakaPay into your application.

***

## Base URL

```
Production: https://app.makapay.io/api
```

***

## Authentication

All API requests require authentication via API key.

### Obtaining an API Key

1. Log in to the [MakaPay Dashboard](https://app.makapay.io/dashboard)
2. Navigate to **API Keys**
3. Click **Create New Key**
4. Copy and securely store your API key

### Using the API Key

Include the API key in the `x-api-key` header:

```
x-api-key: YOUR_API_KEY
```

**Important**: Never expose your API key in client-side code.

***

## Endpoints

### Create Payment

Create a new payment link.

```
POST /payments
```

#### Request Body

| Field                | Type    | Required    | Description                                                                                                                                                                                                                                                                          |
| -------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `merchant`           | string  | Yes         | Ethereum address to receive payment                                                                                                                                                                                                                                                  |
| `chainId`            | string  | Yes         | Target blockchain chain ID                                                                                                                                                                                                                                                           |
| `token`              | string  | Yes         | Token contract address. For ERC-20 tokens, use the contract address. For native tokens (ETH, BNB, MATIC), use the zero address: `0x0000000000000000000000000000000000000000`. See [Supported Networks & Tokens](#supported-networks--tokens) for the full list.                      |
| `amount`             | string  | Conditional | Token-denominated payment amount (human-readable, e.g., "100.00"). Required unless `fiatCurrency` and `fiatAmount` are supplied. Existing integrations can continue using this field unchanged.                                                                                      |
| `fiatCurrency`       | string  | Conditional | Supported ISO 4217 currency code (for example `CHF`, `EUR`, or `GBP`). Must be supplied with `fiatAmount`, without `amount`. Fiat-denominated payments currently require configured USDC on the selected network.                                                                    |
| `fiatAmount`         | string  | Conditional | Positive decimal amount in `fiatCurrency`. Up to 2 decimal places; zero-decimal currencies (JPY, KRW, ISK, HUF) require a whole number.                                                                                                                                              |
| `orderId`            | string  | Yes         | Your internal order reference (max 100 chars)                                                                                                                                                                                                                                        |
| `description`        | string  | No          | Payment description (max 200 chars)                                                                                                                                                                                                                                                  |
| `redirectUrl`        | string  | No          | URL to redirect payer after payment. Payment ID appended as `?makapay=ID` (max 2000 chars)                                                                                                                                                                                           |
| `merchantContact`    | string  | No          | Support contact shown to the payer if something goes wrong (e.g. funds sent on the wrong network): an email, an `https://` link, a Telegram `@handle` or a phone number (max 120 chars). If omitted, the contact from your Settings is used; if neither is set, no contact is shown. |
| `expiresAt`          | number  | No          | Unix timestamp (ms) when payment expires. Shows countdown timer to payer.                                                                                                                                                                                                            |
| `blockConfirmations` | number  | No          | Required confirmations (default: 1, max: 100)                                                                                                                                                                                                                                        |
| `gasless`            | boolean | No          | Enable gasless mode (default: false). **Note:** Only works with stablecoins (USDT, USDC, DAI) or tokens with a known price. Automatically converts to `false` for non-stablecoins without a price.                                                                                   |
| `payerCoversFee`     | boolean | No          | Payer covers fees (default: false)                                                                                                                                                                                                                                                   |
| `customPriceUsd`     | string  | No          | USD price per token for [custom tokens](https://docs.makapay.io/guides/custom-tokens.md) (e.g., "0.00001234"). Used as fallback if Alchemy and TrustedOracle have no price. Required for tokens with no automatic price source.                                                      |

#### Example Request (ERC-20 Token)

```bash
curl -X POST https://app.makapay.io/api/payments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "chainId": "137",
    "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "amount": "50.00",
    "orderId": "order-12345",
    "description": "Premium subscription",
    "blockConfirmations": 1,
    "gasless": false,
    "payerCoversFee": false
  }'
```

#### Example Request (Native Token)

Accept payment in ETH on Ethereum mainnet by passing the zero address as `token`:

```bash
curl -X POST https://app.makapay.io/api/payments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "chainId": "1",
    "token": "0x0000000000000000000000000000000000000000",
    "amount": "0.5",
    "orderId": "order-67890",
    "description": "Payment in ETH"
  }'
```

#### Example Request (Fiat-Denominated USDC)

The server fetches the same stale-protected exchange-rate cache used by POS, applies the merchant's POS global/per-currency spread, and locks the resulting USDC amount when the payment is created.

```bash
curl -X POST https://app.makapay.io/api/payments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "chainId": "137",
    "token": "<POLYGON_USDC_ADDRESS>",
    "fiatCurrency": "CHF",
    "fiatAmount": "50.00",
    "orderId": "ORDER-123",
    "description": "Split bill payment"
  }'
```

#### Response

```json
{
  "url": "https://app.makapay.io/pay/01234567-89ab-cdef-0123-456789abcdef",
  "paymentId": "01234567-89ab-cdef-0123-456789abcdef",
  "fiatCurrency": "CHF",
  "fiatAmount": "50.00",
  "cryptoCurrency": "USDC",
  "cryptoAmount": "62.35",
  "usdEquivalent": "62.344",
  "exchangeRate": "0.8021",
  "rateLockedAt": "2026-07-16T12:00:00.000Z",
  "spreadApplied": 1
}
```

#### Response Fields

| Field                            | Type            | Description                                                                            |
| -------------------------------- | --------------- | -------------------------------------------------------------------------------------- |
| `url`                            | string          | Payment page URL to share with customer                                                |
| `paymentId`                      | string          | Stable payment identifier. Additive for legacy token-denominated requests.             |
| `fiatCurrency`, `fiatAmount`     | string          | Original bill denomination and amount (fiat requests only).                            |
| `cryptoCurrency`, `cryptoAmount` | string          | Locked payment token and payable token amount (fiat requests only).                    |
| `usdEquivalent`                  | string          | USD intermediate value used for USDC conversion (fiat requests only).                  |
| `exchangeRate`                   | string          | Locked effective rate, expressed as fiat units per 1 USD, including configured spread. |
| `rateLockedAt`                   | ISO 8601 string | Time the effective quote was locked.                                                   |
| `spreadApplied`                  | number          | Applied POS spread percentage, when non-zero.                                          |

#### Error Responses

| Status | Error                               | Description                                                                            |
| ------ | ----------------------------------- | -------------------------------------------------------------------------------------- |
| 400    | Invalid form data                   | Request validation failed                                                              |
| 401    | Unauthorized                        | Invalid or missing API key                                                             |
| 422    | RECIPIENT\_NOT\_ALLOWLISTED         | Account has Recipient Wallet enforcement on and `merchant` is not in the verified list |
| 503    | Oracle price unavailable            | Price oracle temporarily unavailable (retry)                                           |
| 503    | Exchange rates unavailable or stale | Fiat quote cannot be safely locked; retry after rates refresh                          |
| 500    | Failed to create payment            | Internal server error                                                                  |

**422 response body** (when the account has [Recipient Wallets](https://docs.makapay.io/security/recipient-wallets.md) enforcement enabled and `merchant` is not in the verified list):

```json
{
  "error": "RECIPIENT_NOT_ALLOWLISTED: Recipient 0x... is not in your verified address book. Add it under Settings → Recipient Wallets first.",
  "code": "RECIPIENT_NOT_ALLOWLISTED",
  "helpUrl": "https://app.makapay.io/dashboard/settings#recipient-wallets"
}
```

Programmatic handling: switch on `code === "RECIPIENT_NOT_ALLOWLISTED"`. The remediation is to add the address under **Dashboard → Settings → Recipient Wallets** (requires a 6-digit 2FA code) and retry the request unchanged. Existing payment links remain valid; the check only runs at creation time.

***

### List Payments

List the merchant's payments, newest first, with cursor pagination.

```
GET /v1/payments
```

Authentication: `x-api-key` header **or** an active dashboard session cookie.

#### Query Parameters

| Param           | Type                       | Default | Description                                                                                                                                                                                                                       |
| --------------- | -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`         | integer (1–100)            | `100`   | Page size.                                                                                                                                                                                                                        |
| `cursor`        | string                     | —       | Opaque cursor returned by the previous page (`nextCursor`). Omit on the first request.                                                                                                                                            |
| `status`        | enum                       | —       | Filter by payment status. One of: `pending`, `paid`, `completed`, `failed`, `expired`, `cancelled`, `withdrawing`, `withdrawn`, `awaiting_gas`, `deploying_wallet`, `withdraw_request`, `waiting_for_confirmation`, `sanctioned`. |
| `createdAfter`  | ISO 8601 string \| Unix ms | —       | Inclusive lower bound on `createdAt`. Combine with `createdBefore` for a range.                                                                                                                                                   |
| `createdBefore` | ISO 8601 string \| Unix ms | —       | Inclusive upper bound on `createdAt`. Must be `>= createdAfter` when both are set.                                                                                                                                                |
| `orderId`       | string                     | —       | Exact-match filter (case-sensitive) on the merchant-supplied `orderId`. Useful for investigating a specific payment.                                                                                                              |

#### Example Request

```bash
curl "https://app.makapay.io/api/v1/payments?limit=50&status=completed" \
  -H "x-api-key: YOUR_API_KEY"
```

Walking the cursor:

```bash
# page 1
curl "https://app.makapay.io/api/v1/payments?limit=100" -H "x-api-key: $KEY"
# page 2 — feed nextCursor back as ?cursor=
curl "https://app.makapay.io/api/v1/payments?limit=100&cursor=<nextCursor>" -H "x-api-key: $KEY"
# repeat until hasMore == false
```

#### Response

```json
{
  "data": [
    {
      "paymentId": "01H...",
      "orderId": "ORDER-123",
      "description": "Invoice #42",
      "status": "completed",
      "createdAt": 1715000000000,
      "completedAt": 1715000060000,
      "expiresAt": 1715003600000,
      "chainId": "8453",
      "token": {
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "decimals": 6
      },
      "amount": "10.00",
      "fiat": {
        "currency": "CHF",
        "amount": 8.02,
        "usdEquivalent": 10,
        "exchangeRate": 0.802,
        "spreadApplied": 1,
        "rateLockedAt": 1752667200000
      },
      "merchant": "0xMerchant...",
      "recipientAddress": "0xWallet...",
      "transaction": {
        "hash": "0xabc...",
        "blockNumber": 12345678,
        "confirmations": 1
      },
      "fees": {
        "platformFee": "0.10",
        "gasFee": "0.01",
        "processingFee": "0.10",
        "totalFee": "0.21",
        "feePercentage": 1
      },
      "gasless": false,
      "payerCoversFee": false,
      "terminal": {
        "terminalId": "term_aZ3kLm9NqP",
        "code": "R1",
        "name": "Register 1"
      }
    }
  ],
  "nextCursor": "eyJ...",
  "hasMore": true
}
```

#### Response Fields

| Field             | Type           | Description                                                                                                                                                                                                                                                                                                                                                   |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data[]`          | array          | Payments on this page, newest first.                                                                                                                                                                                                                                                                                                                          |
| `data[].terminal` | object \| null | POS business info when the payment was created on a business (the `orderId` is `POS-{CODE}-{CASHIER}-{TS}`). `terminalId` is the stable identifier you should store; `code` is the short code embedded in `orderId`; `name` is the dashboard display Location. `null` for regular payment-link payments and for POS payments whose business has been deleted. |
| `data[].fiat`     | object \| null | Original fiat amount, USD equivalent, locked effective exchange rate/spread, and lock timestamp. `null` for legacy token-denominated payments.                                                                                                                                                                                                                |
| `nextCursor`      | string \| null | Pass as `?cursor=` on the next request. `null` when no more pages.                                                                                                                                                                                                                                                                                            |
| `hasMore`         | boolean        | `true` while more pages remain.                                                                                                                                                                                                                                                                                                                               |

#### More Examples

```bash
# Date range — payments created in March 2026
curl "https://app.makapay.io/api/v1/payments?createdAfter=2026-03-01T00:00:00Z&createdBefore=2026-03-31T23:59:59Z" \
  -H "x-api-key: $KEY"

# Date range with Unix ms
curl "https://app.makapay.io/api/v1/payments?createdAfter=1761955200000&createdBefore=1764547199000" \
  -H "x-api-key: $KEY"

# Investigate a specific orderId
curl "https://app.makapay.io/api/v1/payments?orderId=ORDER-12345" \
  -H "x-api-key: $KEY"

# All payments from a specific POS business — filter client-side on `terminal.terminalId`
curl "https://app.makapay.io/api/v1/payments?status=completed&limit=100" \
  -H "x-api-key: $KEY" \
  | jq '.data[] | select(.terminal.terminalId == "term_aZ3kLm9NqP")'
```

#### Error Responses

| Status | code             | When                                                                      |
| ------ | ---------------- | ------------------------------------------------------------------------- |
| 400    | `invalid_query`  | Query parameter failed validation (e.g. unknown `status`, `limit > 100`). |
| 401    | `unauthorized`   | No session and no valid API key.                                          |
| 500    | `internal_error` | Unexpected server failure.                                                |

Error envelope:

```json
{ "error": "Unauthorized", "code": "unauthorized" }
```

***

### Native App Real-Time Checkout

Native iOS and macOS applications can render a MakaPay checkout in their own UI and subscribe directly to a payer-safe Convex projection. Payment creation must still happen on the merchant backend with `POST /payments`; **never embed a MakaPay API key in a mobile application**.

Connect the official `ConvexMobile` Swift package to the production deployment URL supplied by MakaPay, then subscribe to:

```
payment:getPublicCheckout
```

Arguments:

```json
{ "paymentId": "01234567-89ab-7def-8123-456789abcdef" }
```

The query is read-only and requires no API key. Possession of the unguessable payment ID grants payer-level access to that checkout, just as possession of the hosted `/pay/{paymentId}` URL does.

Example Swift subscription:

```swift
import ConvexMobile

let convex = ConvexClient(deploymentUrl: makaPayConvexDeploymentUrl)

let updates = convex.subscribe(
    to: "payment:getPublicCheckout",
    with: ["paymentId": paymentId],
    yielding: PublicCheckout.self
).values

for await checkout in updates {
    // Re-render when pending → detected → confirming/processing → completed.
}
```

Response fields:

| Field                   | Type            | Description                                                                                                                  |
| ----------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `paymentId`             | string          | Stable payment identifier.                                                                                                   |
| `status`                | enum            | Payer-facing lifecycle: `pending`, `detected`, `confirming`, `processing`, `completed`, `failed`, `expired`, or `cancelled`. |
| `isFinal`               | boolean         | Whether no further checkout transition is expected.                                                                          |
| `recipientAddress`      | string          | Address to which the payer sends funds.                                                                                      |
| `amount`                | string          | Required token amount in human-readable units.                                                                               |
| `receivedAmount`        | string?         | Amount detected so far, including partial payments.                                                                          |
| `token`, `tokenSymbol`  | string          | Token address/mint and display symbol.                                                                                       |
| `chainId`               | number          | Settlement network identifier.                                                                                               |
| `family`                | `evm` \| `svm`? | Chain family; absent legacy rows are EVM.                                                                                    |
| `description`           | string?         | Merchant-provided checkout description.                                                                                      |
| `expiresAt`             | number?         | Checkout expiry as Unix milliseconds.                                                                                        |
| `qrCodeUrl`             | string          | Address-only QR image URL. Native apps may instead generate a QR locally from `recipientAddress`.                            |
| `currentConfirmations`  | number          | Current block/slot confirmation count.                                                                                       |
| `requiredConfirmations` | number          | Confirmations required by the payment.                                                                                       |

The public projection intentionally excludes merchant account identifiers, order IDs, redirect URLs, fee configuration, sanctions data, and recovery state. Use signed merchant webhooks as the server-side source of truth for fulfillment.

***

### Create a Universal USDC Payment

Create one logical payment that accepts Circle-native USDC on any enabled source chain. With `destinationChainId`, MakaPay routes the received USDC via Circle CCTP and the merchant receives USDC on the chosen destination chain. The endpoint derives and verifies one identical CREATE2 address against every accepted source factory before storing anything.

```http
POST /v1/payments/universal-usdc
```

This endpoint is additive and does not create a row in the ordinary `payments` system. MakaPay sponsors the source settlement transaction and waives the platform fee. For routed payments, the payer covers Circle's live CCTP protocol and forwarding fee; the merchant receives the full requested amount. `gasless`, `payerCoversFee`, `chainId`, and `token` are intentionally rejected.

Routed requests on this compatibility endpoint execute through MakaPay's CCTP V2 router fleet. Existing clients keep the same `/v1` request and response shape while receiving the currently enabled V2 source and destination routes.

#### Request

```json
{
  "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595F8fE00",
  "fiatCurrency": "CHF",
  "fiatAmount": "50.00",
  "destinationChainId": 1,
  "bridgeSpeed": "fast",
  "acceptedChainIds": [1, 137, 8453],
  "orderId": "ORDER-UNIVERSAL-123",
  "description": "iOS checkout",
  "expiresAt": 1784206800000,
  "blockConfirmations": 2
}
```

| Field                | Type                 | Required    | Description                                                                                                                 |
| -------------------- | -------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| `merchant`           | EVM address          | Yes         | Final merchant recipient. Recipient Wallet enforcement applies.                                                             |
| `amount`             | decimal string       | Conditional | USDC-denominated amount, minimum `0.10`, maximum 6 decimal places. Supply this or the fiat pair, never both.                |
| `fiatCurrency`       | ISO 4217 string      | Conditional | Bill currency such as `EUR`, `CHF`, or `GBP`. Must be supplied with `fiatAmount`, without `amount`.                         |
| `fiatAmount`         | decimal string       | Conditional | Positive bill amount with up to 2 decimals; zero-decimal currencies require a whole number.                                 |
| `orderId`            | string               | Yes         | Merchant-unique order reference, maximum 100 characters. Duplicate IDs are rejected across ordinary and Universal payments. |
| `description`        | string               | No          | Payer-facing description, maximum 200 characters.                                                                           |
| `expiresAt`          | integer              | No          | Unix milliseconds. Only an entirely unfunded payment expires.                                                               |
| `blockConfirmations` | integer              | No          | Required confirmations, 1–100; default 1.                                                                                   |
| `destinationChainId` | integer              | No          | Enables routed settlement to an enabled CCTP destination. Omit for legacy direct mode.                                      |
| `destinationAddress` | EVM address          | No          | Final destination recipient; defaults to `merchant`.                                                                        |
| `bridgeSpeed`        | `fast` \| `standard` | No          | CCTP finality class; default `fast`.                                                                                        |
| `acceptedChainIds`   | integer\[]           | No          | Unique subset of enabled source chains; defaults to all enabled sources.                                                    |

#### Response

```json
{
  "paymentId": "01900000-0000-7000-8000-000000000001",
  "asset": "USDC",
  "amount": "63.131313",
  "cryptoAmount": "63.131313",
  "fiatCurrency": "CHF",
  "fiatAmount": "50.00",
  "usdEquivalent": "63.13131313131313",
  "exchangeRate": "0.792",
  "rateLockedAt": "2026-07-16T12:00:00.000Z",
  "spreadApplied": 1,
  "recipientAddress": "0x1111111111111111111111111111111111111111",
  "qrCodeData": "0x1111111111111111111111111111111111111111",
  "acceptedChainIds": [1, 137, 8453],
  "acceptedNetworks": [
    {
      "chainId": 1,
      "name": "Ethereum",
      "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "decimals": 6
    },
    {
      "chainId": 137,
      "name": "Polygon",
      "token": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
      "decimals": 6
    },
    {
      "chainId": 8453,
      "name": "Base",
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "decimals": 6
    }
  ],
  "monitoringStatus": "active",
  "registeredChainIds": [1, 137, 8453],
  "failedChainIds": [],
  "realtime": {
    "deploymentUrl": "https://knowing-guineapig-268.convex.cloud",
    "query": "universalPayments:getPublicCheckout",
    "args": {
      "paymentId": "01900000-0000-7000-8000-000000000001"
    }
  }
}
```

For routed payments, `amount` / `destinationAmount` is what the merchant must receive. Each `acceptedNetworks` entry additionally contains `payerAmount` and `bridgeFee`, quoted for that exact source-to-destination route from Circle's `/v2/burn/USDC/fees/...?...forward=true` endpoint. Same-chain routes have a zero bridge fee. Integrators must display and collect the selected network's `payerAmount`, not a worst-case amount shared by every network.

For fiat requests, MakaPay applies the merchant's configured currency spread to the latest server-side rate and locks the merchant amount at creation. `amount` and `cryptoAmount` are the same six-decimal destination USDC value; for routed payments, the selected network's `payerAmount` is authoritative for the payer. The original bill and complete immutable quote are preserved in the creation response, public Convex checkout, and merchant webhooks. Fiat quote fields are omitted for token-denominated calls.

`monitoringStatus: "degraded"` means one or more Alchemy registrations could not be confirmed immediately. The payment remains usable: registration retries run in the background and an independent 30-second on-chain balance poller prevents missed webhook delivery from stranding funds.

The first matching USDC balance—even a partial payment—atomically locks the payment to its arrival chain. Repeated Alchemy events are idempotent. A later deposit on another accepted chain is recorded as a chain conflict and cannot change the selected settlement route.

#### Real-Time Swift Subscription

```swift
let updates = convex.subscribe(
    to: "universalPayments:getPublicCheckout",
    with: ["paymentId": paymentId],
    yielding: UniversalUsdcCheckout.self
).values
```

Direct lifecycle: `pending → detected → confirming → processing → completed`. Routed cross-chain lifecycle adds `bridging` before `completed`; completed means the destination mint to the merchant was confirmed. Terminal alternatives are `failed`, `expired`, `cancelled`, and `sanctioned`. Legacy Universal payments already in `awaiting_gas` are automatically retried under the sponsored settlement policy.

The Universal subscription returns `cryptoAmount`, `fiatCurrency`, `fiatAmount`, `usdEquivalent`, `exchangeRate`, `rateLockedAt`, and `spreadApplied` in addition to the common checkout fields. Numeric quote fields use Convex numbers; `cryptoAmount` remains a decimal string to avoid changing the locked USDC precision.

#### Errors

| Status | Code                            | Description                                                                                                                                                            |
| ------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | —                               | Invalid amount/address/currency, both denomination modes supplied, an incomplete fiat pair, or an unsupported field such as `chainId`, `gasless`, or `payerCoversFee`. |
| 401    | —                               | Missing or invalid API key/session.                                                                                                                                    |
| 403    | —                               | Sanctioned merchant address.                                                                                                                                           |
| 409    | `DUPLICATE_ORDER_ID`            | The order ID already exists in either payment system.                                                                                                                  |
| 503    | `UNIVERSAL_ADDRESS_UNAVAILABLE` | A factory could not derive its address. No record was created.                                                                                                         |
| 503    | `UNIVERSAL_ADDRESS_MISMATCH`    | The three factories did not return one identical address. No record was created.                                                                                       |
| 503    | —                               | Exchange rates are unavailable or stale. No record was created.                                                                                                        |

***

### Create a Universal USDC V2 Payment Intent

Create a payer-funded Universal USDC intent from a persistent settlement profile. The profile fixes the destination chain and address, accepted source chains, and CCTP finality preference.

```http
POST /v2/payment-intents
```

#### Request

```json
{
  "settlementProfileId": "k57...",
  "amount": "100.00",
  "orderId": "ORDER-V2-123",
  "description": "Partner checkout",
  "expiresAt": 1784206800000,
  "blockConfirmations": 2
}
```

| Field                 | Type           | Required | Description                                                                         |
| --------------------- | -------------- | -------- | ----------------------------------------------------------------------------------- |
| `settlementProfileId` | string         | Yes      | Active settlement profile owned by the authenticated merchant.                      |
| `amount`              | decimal string | Yes      | USDC amount the merchant must receive, minimum `0.10` and maximum 6 decimal places. |
| `orderId`             | string         | Yes      | Merchant order reference, maximum 100 characters.                                   |
| `description`         | string         | No       | Payer-facing description, maximum 200 characters.                                   |
| `expiresAt`           | integer        | No       | Checkout expiry as Unix milliseconds.                                               |
| `blockConfirmations`  | integer        | No       | Required source confirmations, 1–100; default 1.                                    |

#### CCTP Delivery Mode

`deliveryMode` is not a request field. MakaPay resolves and snapshots it from the exact full API key used to create the intent:

* `forwarding` is the default for all API keys and uses Circle's forwarding service.
* `self-relay` must be explicitly enabled for that full API key by a MakaPay administrator. Scoped keys cannot be enabled, and a replacement or rotated key starts in `forwarding` mode until it is separately approved.

Self-relay is supported only by Universal USDC V2 intents whose settlement profile destination is HyperEVM (chain ID `999`). A self-relay-enabled key used with any other V2 destination is rejected. Universal USDC V1 continues to use `forwarding`.

For `self-relay`, the payer covers only Circle's live CCTP protocol fee. MakaPay service, platform, processing, and gas fees are all zero, and Circle's forwarding fee is zero. MakaPay submits the attested message on the destination chain with its operator-managed CCTP relayer; merchants do not provide a relayer credential or destination gas.

#### Response

```json
{
  "id": "01900000-0000-7000-8000-000000000002",
  "object": "payment_intent",
  "version": 2,
  "status": "pending",
  "asset": "USDC",
  "merchantAmount": "100",
  "deliveryMode": "self-relay",
  "recipientAddress": "0x1111111111111111111111111111111111111111",
  "checkoutUrl": "https://app.makapay.io/pay/usdc/01900000-0000-7000-8000-000000000002",
  "destination": {
    "chainId": 999,
    "name": "HyperEVM",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595F8fE00"
  },
  "routes": [
    {
      "sourceChainId": 8453,
      "sourceChain": "Base",
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "payerAmount": "100.01",
      "fees": {
        "service": "0",
        "forwarding": "0",
        "circle": "0.01",
        "total": "0.01"
      },
      "sameChain": false,
      "finality": "fast",
      "quoteExpiresAt": 1784203500000
    }
  ]
}
```

`deliveryMode` is always explicit and is either `forwarding` or `self-relay`. Each route is quoted independently; collect its `payerAmount`, which equals `merchantAmount + fees.total`.

`fees.forwarding` explicitly reports Circle's forwarding component. It is already included in `fees.circle` when `deliveryMode` is `forwarding`, so do not add it a second time. In `self-relay` mode, `fees.service` and `fees.forwarding` are both `"0"`, `fees.circle` contains only Circle's protocol fee, and `fees.total` equals `fees.circle`.

***

### Get Balance

Get your Gas Tank balance.

```
GET /balance
```

#### Example Request

```bash
curl https://app.makapay.io/api/balance \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "balance": "25.500000"
}
```

#### Response Fields

| Field     | Type   | Description                                   |
| --------- | ------ | --------------------------------------------- |
| `balance` | string | Current Gas Tank balance in USDT (6 decimals) |

***

### Verify Payment Redirect

Verify that a payment redirect is authentic. Use this after receiving a redirect from MakaPay to confirm the payment was actually completed.

```
GET /payments/verify?id=PAYMENT_ID&hash=HASH
```

**Note:** This endpoint does not require authentication, as the hash serves as verification.

#### Query Parameters

| Parameter | Type   | Required | Description                                        |
| --------- | ------ | -------- | -------------------------------------------------- |
| `id`      | string | Yes      | The payment ID from the redirect (`makapay` param) |
| `hash`    | string | Yes      | The verification hash from the redirect            |

#### Example Request

```bash
curl "https://app.makapay.io/api/payments/verify?id=01234567-89ab-cdef&hash=abc123..."
```

#### Success Response

```json
{
  "valid": true,
  "verified": true,
  "payment": {
    "paymentId": "01234567-89ab-cdef-0123-456789abcdef",
    "orderId": "order-12345",
    "status": "completed",
    "amount": "50.00",
    "receivedAmount": "50.00",
    "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "chainId": 137,
    "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "transactionHash": "0x...",
    "completedAt": 1705312200000
  }
}
```

#### Response Fields

| Field                 | Type    | Description                                                   |
| --------------------- | ------- | ------------------------------------------------------------- |
| `valid`               | boolean | Whether the hash is valid                                     |
| `verified`            | boolean | Whether hash is valid AND payment is completed                |
| `payment`             | object  | Payment details (only if valid)                               |
| `payment.completedAt` | number  | Unix timestamp when payment was completed (only if completed) |
| `error`               | string  | Error message (only if invalid)                               |

#### Error Responses

| Status | Error              | Description                      |
| ------ | ------------------ | -------------------------------- |
| 400    | Missing payment ID | No `id` parameter provided       |
| 400    | Missing hash       | No `hash` parameter provided     |
| 400    | Invalid hash       | Hash does not match payment data |
| 404    | Payment not found  | Payment ID does not exist        |

***

## Redirect Verification Flow

When you configure a `redirectUrl` for a payment, MakaPay will redirect the payer to your URL after successful payment with these query parameters:

```
https://yoursite.com/success?makapay=PAYMENT_ID&success=true&hash=HASH
```

### Query Parameters

| Parameter | Description                                             |
| --------- | ------------------------------------------------------- |
| `makapay` | The unique payment ID                                   |
| `success` | Always `"true"` (redirect only happens on success)      |
| `hash`    | HMAC-SHA256 signature (server-signed, cannot be forged) |

### Security

The `hash` parameter is an HMAC-SHA256 signature computed with a server-side secret. This ensures:

* **Attackers cannot forge redirect URLs** - The secret is never exposed
* **Merchants must verify via API** - Only MakaPay's server can validate the signature

> **Important:** Always verify redirects using the `/api/payments/verify` endpoint. Never trust redirect parameters alone.

### Verification Steps

1. **Extract parameters** from the redirect URL
2. **Call the verify endpoint** to confirm authenticity:

   ```
   GET /api/payments/verify?id={makapay}&hash={hash}
   ```
3. **Check the response**:
   * `verified: true` = Payment is complete and authentic
   * `verified: false` = Do not trust the redirect

### Example Implementation (Node.js)

```javascript
app.get('/payment/success', async (req, res) => {
  const { makapay, hash } = req.query;

  // ALWAYS verify with MakaPay API - never trust redirect params alone
  const response = await fetch(
    `https://app.makapay.io/api/payments/verify?id=${makapay}&hash=${hash}`
  );
  const result = await response.json();

  if (result.verified) {
    // Payment confirmed! Update your order
    await updateOrder(result.payment.orderId, 'paid');
    res.render('success', { payment: result.payment });
  } else {
    // Invalid redirect - possible fraud attempt
    res.status(400).render('error', { message: 'Payment verification failed' });
  }
});
```

***

## Payment Expiration

You can set an expiration time on payment links to create urgency or limit the validity period. When a payment expires, the payer will see an "Expired" status instead of being able to pay.

### How It Works

1. **Set expiration** when creating a payment using the `expiresAt` field (Unix timestamp in milliseconds)
2. **Countdown timer** is shown to the payer on the payment page
3. **Automatic expiration** - a background job checks and expires payments every minute
4. **Grace period** - payments already received are processed even if the link expires

### Common Expiration Durations

| Duration | Calculation                                  |
| -------- | -------------------------------------------- |
| 1 hour   | `Date.now() + 3600000`                       |
| 24 hours | `Date.now() + 86400000`                      |
| 7 days   | `Date.now() + 604800000`                     |
| Custom   | `new Date('2025-01-20T12:00:00Z').getTime()` |

### Example: Payment with 1-Hour Expiration

```bash
curl -X POST https://app.makapay.io/api/payments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "chainId": "137",
    "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "amount": "50.00",
    "orderId": "flash-sale-001",
    "description": "Flash sale - limited time offer",
    "expiresAt": '"$(node -e "console.log(Date.now() + 3600000)")"',
    "gasless": true
  }'
```

### Example: Dynamic Expiration (Node.js)

```javascript
async function createTimeLimitedPayment(order, hoursValid = 24) {
  const expiresAt = Date.now() + (hoursValid * 60 * 60 * 1000);

  const response = await fetch('https://app.makapay.io/api/payments', {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      merchant: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
      chainId: '137',
      token: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
      amount: order.total.toString(),
      orderId: order.id,
      description: order.description,
      expiresAt: expiresAt,  // Payment expires in X hours
      gasless: true,
    }),
  });

  return response.json();
}

// Create a payment that expires in 1 hour
const payment = await createTimeLimitedPayment(order, 1);
```

### Payment States After Expiration

| Status      | Description                                          |
| ----------- | ---------------------------------------------------- |
| `expired`   | Payment link expired before any payment was received |
| `completed` | Payment was received before expiration and processed |
| `pending`   | Payment partially received, may still be processed   |

### Best Practices

1. **Use expiration for time-sensitive offers** - flash sales, limited-time discounts
2. **Allow reasonable time** - consider timezone differences and payment processing time
3. **Communicate clearly** - show expiration time in your UI before redirecting to payment
4. **Handle expired state** - provide a way for customers to request a new payment link

***

## Public Endpoints

The following endpoints are **public** and do not require authentication. They are useful for resolving token information before creating a payment.

### Get Token Price

Look up the current USD price for any token. The price is resolved using a two-step waterfall:

1. **Alchemy** — checked first using `chainId` + `address`. Works for most popular tokens on major chains.
2. **TrustedOracle** — fallback if Alchemy has no price. The oracle looks up prices by symbol, so the optional `symbol` parameter is needed for this fallback to work. If you omit `symbol` and Alchemy doesn't have the price, the endpoint returns 404.

```
GET /tokens/price
```

**Note:** This endpoint does not require authentication.

#### Query Parameters

| Parameter | Type   | Required | Description                                                                                                                                                                                                           |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chainId` | string | Yes      | Blockchain chain ID (e.g., `1` for Ethereum, `137` for Polygon)                                                                                                                                                       |
| `address` | string | Yes      | Token contract address (checksummed or lowercase)                                                                                                                                                                     |
| `symbol`  | string | No       | Token symbol (e.g., `ETH`, `BNB`). Only needed for the TrustedOracle fallback — if Alchemy already has a price for this token, the symbol is not used. Pass it when you want full coverage across both price sources. |

#### Example Request

```bash
# With symbol — enables both Alchemy and oracle fallback
curl "https://app.makapay.io/api/tokens/price?chainId=1&address=0xdAC17F958D2ee523a2206206994597C13D831ec7&symbol=USDT"

# Without symbol — Alchemy only, no oracle fallback
curl "https://app.makapay.io/api/tokens/price?chainId=1&address=0xdAC17F958D2ee523a2206206994597C13D831ec7"
```

#### Response

```json
{
  "chainId": 1,
  "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "symbol": "USDT",
  "priceUsd": "0.999847",
  "source": "alchemy",
  "timestamp": "2026-02-21T12:00:00.000Z"
}
```

#### Response Fields

| Field       | Type           | Description                                          |
| ----------- | -------------- | ---------------------------------------------------- |
| `chainId`   | number         | The chain ID queried                                 |
| `address`   | string         | Token contract address (lowercased)                  |
| `symbol`    | string \| null | Token symbol (uppercased), or `null` if not provided |
| `priceUsd`  | string         | USD price as a human-readable decimal string         |
| `source`    | string         | Price source used: `"alchemy"` or `"trusted_oracle"` |
| `timestamp` | string         | ISO 8601 timestamp of the response                   |

#### Error Responses

| Status | Error                              | Description                             |
| ------ | ---------------------------------- | --------------------------------------- |
| 400    | chainId and address are required   | Missing required parameters             |
| 400    | chainId must be a number           | Invalid chain ID format                 |
| 400    | Invalid token address              | Address is not a valid Ethereum address |
| 404    | Price not available for this token | No price source could resolve a price   |
| 500    | Failed to fetch token price        | Internal server error                   |

***

### Get Token Metadata

Resolve token metadata (name, symbol, decimals, logo) for any ERC-20 token. Uses Alchemy metadata with on-chain contract read as fallback.

```
GET /tokens/metadata
```

**Note:** This endpoint does not require authentication.

#### Query Parameters

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `chainId` | string | Yes      | Blockchain chain ID    |
| `address` | string | Yes      | Token contract address |

#### Example Request

```bash
curl "https://app.makapay.io/api/tokens/metadata?chainId=137&address=0xc2132D05D31c914a87C6611C10748AEb04B58e8F"
```

#### Response

```json
{
  "name": "Tether USD",
  "symbol": "USDT",
  "decimals": 6,
  "logo": "https://static.alchemyapi.io/images/assets/825.png",
  "hasAlchemyPrice": true,
  "priceUsd": "0.999847",
  "address": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "chainId": 137
}
```

#### Response Fields

| Field             | Type                | Description                                     |
| ----------------- | ------------------- | ----------------------------------------------- |
| `name`            | string \| null      | Token name from metadata                        |
| `symbol`          | string \| null      | Token ticker symbol                             |
| `decimals`        | number              | Token decimals (e.g., 6 for USDT, 18 for ETH)   |
| `logo`            | string \| null      | URL to the token logo image                     |
| `hasAlchemyPrice` | boolean             | Whether Alchemy has a price feed for this token |
| `priceUsd`        | string \| undefined | Current USD price if available from Alchemy     |
| `address`         | string              | Token contract address (lowercased)             |
| `chainId`         | number              | The chain ID queried                            |

#### Error Responses

| Status | Error                            | Description                                                            |
| ------ | -------------------------------- | ---------------------------------------------------------------------- |
| 400    | chainId and address are required | Missing required parameters                                            |
| 400    | chainId must be a number         | Invalid chain ID format                                                |
| 400    | Invalid token address            | Address is not a valid Ethereum address                                |
| 400    | Cannot read token contract       | Contract doesn't exist at this address/chain or is not an ERC-20 token |
| 500    | Failed to fetch token metadata   | Internal server error                                                  |

***

### Get Oracle Price

Fetch the price of a token directly from the MakaPay TrustedOracle smart contract on MakaChain. This is the same oracle used internally for gas fee calculations and as the fallback in the `/tokens/price` waterfall.

Unlike `/tokens/price` (which resolves by chain + address), this endpoint resolves by **symbol only** — it does not need a chain ID or contract address. Use this when you already know the token symbol and just need its USD price.

```
GET /oracle/price
```

**Note:** This endpoint does not require authentication.

#### Query Parameters

| Parameter | Type   | Required | Description                                                                                                 |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `symbol`  | string | Yes      | Token symbol (e.g., `ETH`, `BNB`, `USDT`). Case-insensitive. `USDT0` is automatically normalized to `USDT`. |

#### Example Request

```bash
curl "https://app.makapay.io/api/oracle/price?symbol=ETH"
```

#### Response

```json
{
  "symbol": "ETH",
  "priceRaw": "2735420000000000000000",
  "priceUsd": "2735.42",
  "decimals": 18
}
```

#### Response Fields

| Field      | Type   | Description                                                  |
| ---------- | ------ | ------------------------------------------------------------ |
| `symbol`   | string | Normalized token symbol (uppercased)                         |
| `priceRaw` | string | Raw price as a big integer string (18 decimals of precision) |
| `priceUsd` | string | USD price as a human-readable decimal string                 |
| `decimals` | number | Precision of `priceRaw` (always `18`)                        |

#### Error Responses

| Status | Error                            | Description                                   |
| ------ | -------------------------------- | --------------------------------------------- |
| 400    | Symbol parameter is required     | Missing `symbol` query parameter              |
| 404    | Price not available for {SYMBOL} | Oracle has no price registered for this token |
| 500    | Failed to fetch price            | Internal server error                         |

#### Supported Symbols

The oracle supports all tokens that have been registered by the MakaPay operator. Common symbols include:

| Symbol  | Description                       |
| ------- | --------------------------------- |
| `ETH`   | Ethereum                          |
| `BNB`   | BNB (Binance Smart Chain)         |
| `MATIC` | Polygon                           |
| `USDT`  | Tether USD (also matches `USDT0`) |
| `USDC`  | USD Coin                          |
| `XRP`   | XRP                               |
| `TRX`   | Tron                              |
| `MAKA`  | MAKA Token                        |

***

## Supported Networks & Tokens

### Mainnet

#### Ethereum (Chain ID: 1)

| Token | Contract Address                             | Decimals | Type       |
| ----- | -------------------------------------------- | -------- | ---------- |
| ETH   | `0x0000000000000000000000000000000000000000` | 18       | Native     |
| USDT  | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | 6        | Stablecoin |
| USDC  | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | 6        | Stablecoin |
| MAKA  | `0x52076923f24dAF4c9dA90082b6384EDCC4180646` | 18       | Token      |

#### Polygon (Chain ID: 137)

| Token | Contract Address                             | Decimals | Type       |
| ----- | -------------------------------------------- | -------- | ---------- |
| MATIC | `0x0000000000000000000000000000000000000000` | 18       | Native     |
| USDT0 | `0xc2132D05D31c914a87C6611C10748AEb04B58e8F` | 6        | Stablecoin |
| USDC  | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` | 6        | Stablecoin |

#### BNB Smart Chain (Chain ID: 56)

| Token | Contract Address                             | Decimals | Type       |
| ----- | -------------------------------------------- | -------- | ---------- |
| BNB   | `0x0000000000000000000000000000000000000000` | 18       | Native     |
| USDT  | `0x55d398326f99059ff775485246999027b3197955` | 18       | Stablecoin |
| USDC  | `0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d` | 18       | Stablecoin |
| XRP   | `0x1d2f0da169ceb9fc7b3144628db156f3f6c60dbe` | 18       | Token      |
| TRX   | `0xce7de646e7208a4ef112cb6ed5038fa6cc6b12e3` | 6        | Token      |

#### Base (Chain ID: 8453)

| Token | Contract Address                             | Decimals | Type       |
| ----- | -------------------------------------------- | -------- | ---------- |
| ETH   | `0x0000000000000000000000000000000000000000` | 18       | Native     |
| USDC  | `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913` | 6        | Stablecoin |

#### Arbitrum One (Chain ID: 42161)

| Token | Contract Address                             | Decimals | Type       |
| ----- | -------------------------------------------- | -------- | ---------- |
| ETH   | `0x0000000000000000000000000000000000000000` | 18       | Native     |
| USDT  | `0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9` | 6        | Stablecoin |
| USDC  | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | 6        | Stablecoin |

#### MakaChain (Chain ID: 777178)

| Token | Contract Address                             | Decimals | Type       |
| ----- | -------------------------------------------- | -------- | ---------- |
| USDT  | `0x30C28E393E0732335235685B345c95E6465Ad8A5` | 6        | Stablecoin |
| USDC  | `0x1C978Ed2de920eA6c5844d011Ab9f574979F82A6` | 6        | Stablecoin |

> **Native tokens** use the zero address (`0x000...000`). When creating a payment with a native token, pass the zero address as the `token` parameter.

### Testnet

#### Sepolia (Chain ID: 11155111)

| Token | Contract Address                             | Decimals | Type       |
| ----- | -------------------------------------------- | -------- | ---------- |
| ETH   | `0x0000000000000000000000000000000000000000` | 18       | Native     |
| USDT  | `0x3B62e45fB977773c2eF0404d80e0C59de22A97ec` | 6        | Stablecoin |
| USDC  | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` | 6        | Stablecoin |

#### MakaChain Testnet (Chain ID: 777177)

| Token | Contract Address                             | Decimals | Type       |
| ----- | -------------------------------------------- | -------- | ---------- |
| USDT  | `0x309F410f92A98e43E1EEF623015a2e784F80ed72` | 6        | Stablecoin |
| USDC  | `0x1C978Ed2de920eA6c5844d011Ab9f574979F82A6` | 6        | Stablecoin |

***

## Webhooks

Configure webhooks to receive real-time payment notifications.

### Setup

1. Go to **Dashboard > Webhooks**
2. Enter your webhook URL (HTTPS required)
3. Save configuration

### Webhook Payload

```json
{
  "event": "payment.completed",
  "paymentId": "01234567-89ab-cdef-0123-456789abcdef",
  "orderId": "order-12345",
  "status": "completed",
  "amount": "50.00",
  "receivedAmount": "50.00",
  "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
  "chainId": 137,
  "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
  "transactionHash": "0x...",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

### Event Types

| Event               | Description                  |
| ------------------- | ---------------------------- |
| `payment.completed` | Payment successfully settled |
| `payment.failed`    | Settlement failed            |
| `payment.expired`   | Payment link expired         |

### Retry Policy

* Failed deliveries are retried up to 3 times
* Retry intervals: 1 minute, 5 minutes, 30 minutes
* View delivery logs in the dashboard

***

## Code Examples

### Node.js

```javascript
const axios = require('axios');

const API_KEY = 'your_api_key';
const BASE_URL = 'https://app.makapay.io/api';

async function createPayment(orderData) {
  const response = await axios.post(
    `${BASE_URL}/payments`,
    {
      merchant: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
      chainId: '137',
      token: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
      amount: orderData.total.toString(),
      orderId: orderData.id,
      description: `Order #${orderData.id}`,
    },
    {
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json',
      },
    }
  );

  return response.data.url;
}

// Usage
const paymentUrl = await createPayment({
  id: 'order-12345',
  total: 99.99,
});
console.log('Payment URL:', paymentUrl);
```

### Python

```python
import requests

API_KEY = 'your_api_key'
BASE_URL = 'https://app.makapay.io/api'

def create_payment(order_data):
    response = requests.post(
        f'{BASE_URL}/payments',
        json={
            'merchant': '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
            'chainId': '137',
            'token': '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
            'amount': str(order_data['total']),
            'orderId': order_data['id'],
            'description': f"Order #{order_data['id']}",
        },
        headers={
            'x-api-key': API_KEY,
            'Content-Type': 'application/json',
        }
    )
    response.raise_for_status()
    return response.json()['url']

# Usage
payment_url = create_payment({
    'id': 'order-12345',
    'total': 99.99,
})
print(f'Payment URL: {payment_url}')
```

### PHP

```php
<?php
$api_key = 'your_api_key';
$base_url = 'https://app.makapay.io/api';

function createPayment($orderData) {
    global $api_key, $base_url;

    $ch = curl_init();

    curl_setopt_array($ch, [
        CURLOPT_URL => "$base_url/payments",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            "x-api-key: $api_key",
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'merchant' => '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
            'chainId' => '137',
            'token' => '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
            'amount' => (string)$orderData['total'],
            'orderId' => $orderData['id'],
            'description' => "Order #{$orderData['id']}",
        ]),
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);
    return $data['url'];
}

// Usage
$paymentUrl = createPayment([
    'id' => 'order-12345',
    'total' => 99.99,
]);
echo "Payment URL: $paymentUrl\n";
```

***

## Rate Limits

| Endpoint                            | Rate Limit                  |
| ----------------------------------- | --------------------------- |
| `POST /payments`                    | 100 requests/minute         |
| `GET /balance`                      | 60 requests/minute          |
| Vault config endpoints              | 100 requests/minute         |
| `POST /vault/v1/users`              | 100 requests/minute         |
| `GET /vault/v1/deposits`            | 100 requests/minute         |
| `GET /vault/v1/business/:id/tokens` | 60 requests/minute (per IP) |

Exceeding rate limits returns HTTP 429 (Too Many Requests).

***

## Error Handling

### Error Response Format

```json
{
  "error": "Error message describing what went wrong"
}
```

### Common Errors

| Status | Error                            | Solution                                                |
| ------ | -------------------------------- | ------------------------------------------------------- |
| 400    | Invalid Merchant address format  | Verify the merchant address is a valid Ethereum address |
| 400    | Invalid Token address format     | Verify the token contract address                       |
| 400    | Invalid network selected         | Use a supported chain ID                                |
| 400    | Amount must be a positive number | Ensure amount is > 0                                    |
| 401    | Unauthorized                     | Check your API key                                      |
| 503    | Oracle price unavailable         | Retry after a few seconds                               |

***

## Vault Configuration API

Configure your vault account, manage accepted tokens, and set up webhooks — all via the API. These endpoints require authentication via the `x-api-key` header.

For an overview of the Vault system, see the [Vault System guide](https://docs.makapay.io/guides/vault.md).

***

### Setup Vault

Create a new vault account. Call this once to initialize your vault.

```
POST /vault/v1/config
```

#### Request Body

| Field           | Type   | Required | Description                                |
| --------------- | ------ | -------- | ------------------------------------------ |
| `businessName`  | string | Yes      | Your business display name                 |
| `walletAddress` | string | Yes      | EVM address where processed funds are sent |
| `enabledTokens` | array  | No       | Initial tokens to enable (see below)       |

Each item in `enabledTokens`:

| Field         | Type   | Required | Description                 |
| ------------- | ------ | -------- | --------------------------- |
| `chainId`     | number | Yes      | Blockchain chain ID         |
| `token`       | string | Yes      | Token contract address      |
| `tokenSymbol` | string | Yes      | Token symbol (max 20 chars) |

#### Example Request

```bash
curl -X POST https://app.makapay.io/api/vault/v1/config \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "My Casino",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "enabledTokens": [
      {
        "chainId": 137,
        "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
        "tokenSymbol": "USDT"
      }
    ]
  }'
```

#### Response (201 Created)

```json
{
  "success": true,
  "data": {
    "publicId": "biz_abc123def456",
    "businessName": "My Casino",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "feeBps": 100,
    "isActive": true,
    "enabledTokens": [
      {
        "chainId": 137,
        "tokenSymbol": "USDT",
        "tokenAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F"
      }
    ]
  }
}
```

#### Error Responses

| Status | Error                     | Description                                    |
| ------ | ------------------------- | ---------------------------------------------- |
| 400    | businessName is required  | Missing business name                          |
| 400    | walletAddress is required | Missing wallet address                         |
| 400    | Invalid EVM address       | Wallet address is not a valid Ethereum address |
| 401    | Unauthorized              | Missing or invalid API key                     |
| 409    | Vault already configured  | Vault already exists for this API key          |

***

### Get Vault Configuration

Retrieve your current vault configuration.

```
GET /vault/v1/config
```

#### Example Request

```bash
curl https://app.makapay.io/api/vault/v1/config \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "success": true,
  "data": {
    "publicId": "biz_abc123def456",
    "businessName": "My Casino",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "feeBps": 100,
    "isActive": true,
    "enabledTokens": [
      {
        "chainId": 137,
        "tokenSymbol": "USDT",
        "tokenAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F"
      }
    ]
  }
}
```

#### Error Responses

| Status | Error                | Description                      |
| ------ | -------------------- | -------------------------------- |
| 401    | Unauthorized         | Missing or invalid API key       |
| 404    | Vault not configured | No vault exists for this API key |

***

### Update Vault Settings

Update your vault's business name, wallet address, or active status.

```
PATCH /vault/v1/config
```

#### Request Body

All fields are optional — include only what you want to change.

| Field           | Type    | Required | Description                                                                                                                                                                                                                                                                |
| --------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `businessName`  | string  | No       | New business name                                                                                                                                                                                                                                                          |
| `walletAddress` | string  | No       | New wallet address (valid EVM address). Auto-Conversion users keep their deposit address and pay out to the new wallet; all other users get a new deposit address. See [Changing your payout wallet](https://docs.makapay.io/guides/vault.md#changing-your-payout-wallet). |
| `isActive`      | boolean | No       | Enable/disable the vault                                                                                                                                                                                                                                                   |

#### Example Request

```bash
curl -X PATCH https://app.makapay.io/api/vault/v1/config \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Casino Royale",
    "isActive": true
  }'
```

#### Response

```json
{
  "success": true,
  "data": {
    "businessName": "Casino Royale",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "isActive": true
  }
}
```

#### Error Responses

| Status | Error                | Description                      |
| ------ | -------------------- | -------------------------------- |
| 400    | Invalid EVM address  | New wallet address is invalid    |
| 401    | Unauthorized         | Missing or invalid API key       |
| 404    | Vault not configured | No vault exists for this API key |

***

### Add Token

Enable a new token for deposits on your vault.

```
POST /vault/v1/config/tokens
```

#### Request Body

| Field                   | Type   | Required | Description                        |
| ----------------------- | ------ | -------- | ---------------------------------- |
| `chainId`               | number | Yes      | Blockchain chain ID (1–999999999)  |
| `token`                 | string | Yes      | Token contract address             |
| `tokenSymbol`           | string | Yes      | Token ticker symbol (max 20 chars) |
| `minDepositAmountCents` | number | No       | Minimum deposit in USD cents       |
| `maxDepositAmountCents` | number | No       | Maximum deposit in USD cents       |

#### Example Request

```bash
curl -X POST https://app.makapay.io/api/vault/v1/config/tokens \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 56,
    "token": "0x55d398326f99059ff775485246999027b3197955",
    "tokenSymbol": "USDT",
    "minDepositAmountCents": 100,
    "maxDepositAmountCents": 1000000
  }'
```

#### Response (201 Created)

```json
{
  "success": true,
  "data": {
    "chainId": 56,
    "tokenSymbol": "USDT",
    "tokenAddress": "0x55d398326f99059ff775485246999027b3197955"
  }
}
```

#### Error Responses

| Status | Error                   | Description                        |
| ------ | ----------------------- | ---------------------------------- |
| 400    | chainId is required     | Missing chain ID                   |
| 400    | tokenSymbol is required | Missing token symbol               |
| 400    | tokenSymbol too long    | Symbol exceeds 20 characters       |
| 401    | Unauthorized            | Missing or invalid API key         |
| 404    | Vault not configured    | No vault exists for this API key   |
| 409    | Token already enabled   | Token already exists on this chain |

***

### Remove Token

Remove a token from your vault's accepted list.

```
DELETE /vault/v1/config/tokens
```

#### Request Body

| Field     | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `chainId` | number | Yes      | Chain ID of the token to remove |
| `token`   | string | Yes      | Token contract address          |

#### Example Request

```bash
curl -X DELETE https://app.makapay.io/api/vault/v1/config/tokens \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 56,
    "token": "0x55d398326f99059ff775485246999027b3197955"
  }'
```

#### Response

```json
{
  "success": true,
  "data": {
    "removedToken": "USDT",
    "removedChainId": 56,
    "remainingTokens": [
      {
        "chainId": 137,
        "tokenSymbol": "USDT",
        "tokenAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F"
      }
    ]
  }
}
```

#### Error Responses

| Status | Error                          | Description                      |
| ------ | ------------------------------ | -------------------------------- |
| 400    | chainId and token are required | Missing required fields          |
| 401    | Unauthorized                   | Missing or invalid API key       |
| 404    | Token not found                | Token is not in the enabled list |

***

### Get Webhook Configuration

Retrieve your current webhook settings.

```
GET /vault/v1/config/webhooks
```

#### Example Request

```bash
curl https://app.makapay.io/api/vault/v1/config/webhooks \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "success": true,
  "data": {
    "url": "https://yoursite.com/webhook/vault",
    "events": [
      "deposit.completed", "deposit.failed",
      "withdrawal.requested", "withdrawal.completed",
      "withdrawal.rejected", "withdrawal.failed"
    ],
    "isActive": true,
    "secretPreview": "whsec_************************abc12345"
  }
}
```

> **Note:** The full secret is only shown when first creating the webhook or after regenerating. Subsequent reads show a masked preview.

#### Error Responses

| Status | Error                 | Description                |
| ------ | --------------------- | -------------------------- |
| 401    | Unauthorized          | Missing or invalid API key |
| 404    | No webhook configured | No webhook has been set up |

***

### Create / Update Webhook

Set up or update your vault webhook endpoint. The webhook URL must use HTTPS.

```
PUT /vault/v1/config/webhooks
```

#### Request Body

| Field      | Type      | Required | Description                            |
| ---------- | --------- | -------- | -------------------------------------- |
| `url`      | string    | Yes      | Webhook URL (must be HTTPS)            |
| `events`   | string\[] | No       | Events to subscribe to (default: all)  |
| `isActive` | boolean   | No       | Enable/disable webhook (default: true) |

Omitting `events` subscribes the webhook to every event below — that is the default, and the one you want unless you have a reason to narrow it. If you do send an explicit list it **replaces** the whole set, so keep `withdrawal.rejected` in it: that event is how your backend learns to give a player their balance back when a payout is declined.

Available events: `deposit.completed`, `deposit.failed`, `deposit.detected`, `deposit.processing`, `withdrawal.requested`, `withdrawal.completed`, `withdrawal.rejected`, `withdrawal.failed`. Use the wildcards `deposit.*` or `withdrawal.*` to subscribe to all events of that type.

#### Example Request

```bash
curl -X PUT https://app.makapay.io/api/vault/v1/config/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhook/vault",
    "events": [
      "deposit.completed", "deposit.failed",
      "withdrawal.requested", "withdrawal.completed",
      "withdrawal.rejected", "withdrawal.failed"
    ],
    "isActive": true
  }'
```

#### Response (first time — includes secret)

```json
{
  "success": true,
  "data": {
    "url": "https://yoursite.com/webhook/vault",
    "events": [
      "deposit.completed", "deposit.failed",
      "withdrawal.requested", "withdrawal.completed",
      "withdrawal.rejected", "withdrawal.failed"
    ],
    "isActive": true,
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  }
}
```

#### Response (update — secret is masked)

```json
{
  "success": true,
  "data": {
    "url": "https://yoursite.com/webhook/vault",
    "events": [
      "deposit.completed", "deposit.failed",
      "withdrawal.requested", "withdrawal.completed",
      "withdrawal.rejected", "withdrawal.failed"
    ],
    "isActive": true,
    "secretPreview": "whsec_************************abc12345"
  }
}
```

> **Important:** Save the `secret` from the first response — it is only shown once. Use it to verify webhook signatures.

#### Error Responses

| Status | Error                      | Description                      |
| ------ | -------------------------- | -------------------------------- |
| 400    | Webhook URL must use HTTPS | URL protocol is not HTTPS        |
| 400    | Invalid webhook URL        | URL format is invalid            |
| 401    | Unauthorized               | Missing or invalid API key       |
| 404    | Vault not configured       | No vault exists for this API key |

***

### Delete Webhook

Remove the webhook configuration entirely.

```
DELETE /vault/v1/config/webhooks
```

#### Example Request

```bash
curl -X DELETE https://app.makapay.io/api/vault/v1/config/webhooks \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "success": true,
  "data": null
}
```

#### Error Responses

| Status | Error                 | Description                 |
| ------ | --------------------- | --------------------------- |
| 401    | Unauthorized          | Missing or invalid API key  |
| 404    | No webhook configured | No webhook exists to delete |

***

### Regenerate Webhook Secret

Generate a new HMAC secret for webhook signature verification. The old secret immediately stops working.

> **Warning:** If you regenerate the secret while webhook deliveries are in the retry queue, those retries will use the **new** secret. Ensure your server is updated to verify with the new secret before triggering a regeneration, or briefly pause the webhook (`isActive: false`) while rotating.

```
POST /vault/v1/config/webhooks
```

#### Request Body

```json
{
  "action": "regenerate-secret"
}
```

#### Example Request

```bash
curl -X POST https://app.makapay.io/api/vault/v1/config/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "regenerate-secret"}'
```

#### Response

```json
{
  "success": true,
  "data": {
    "secret": "whsec_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4"
  }
}
```

> **Important:** Save this new secret immediately. The old secret is permanently invalidated. Update your webhook handler with the new secret.

#### Error Responses

| Status | Error                 | Description                 |
| ------ | --------------------- | --------------------------- |
| 401    | Unauthorized          | Missing or invalid API key  |
| 404    | No webhook configured | Must create a webhook first |

***

## Vault Withdrawals API

Create and manage **non-custodial** withdrawal requests. Your backend files a withdrawal request; an operator approves it in the MakaPay dashboard (**Platform Wallets → Withdrawals**) by signing the payout **from your own wallet** (browser wallet or WalletConnect QR), and MakaPay verifies the transfer on-chain before marking it completed. MakaPay never holds or moves funds and charges no fee on withdrawals — your wallet pays only network gas.

These endpoints require authentication via the `x-api-key` header. For the full withdrawal flow, lifecycle, and webhook payloads, see the [Vault System guide](https://docs.makapay.io/guides/vault.md#withdrawals).

#### Withdrawal Statuses

| Status       | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| `pending`    | Awaiting operator decision in the dashboard                          |
| `approving`  | Operator is signing the payout in their wallet                       |
| `confirming` | Payout transaction broadcast — MakaPay is verifying it on-chain      |
| `completed`  | Payout verified on-chain — final                                     |
| `rejected`   | Declined by the operator or cancelled via API — re-credit the player |
| `failed`     | Payout transaction reverted or could not be verified                 |

#### Withdrawal Webhooks

Withdrawal events (`withdrawal.requested`, `withdrawal.completed`, `withdrawal.rejected`, `withdrawal.failed`, or the `withdrawal.*` wildcard) are delivered through the same vault webhook configuration — same URL, secret, and signature scheme as deposit webhooks. Withdrawal webhooks are retried up to 3 times (immediately, after 5 minutes, and after 10 minutes) until your endpoint returns a 2xx, so make your handler idempotent on (`event`, `data.withdrawalId`). See the [Vault System guide](https://docs.makapay.io/guides/vault.md#webhooks) for payload fields and signature verification.

***

### Create Withdrawal Request

Submit a withdrawal request for operator approval.

```
POST /vault/v1/withdrawals
```

#### Request Body

| Field                  | Type   | Required | Description                                                                                                                                     |
| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `externalUserId`       | string | Yes      | Your internal user ID                                                                                                                           |
| `externalWithdrawalId` | string | Yes      | Your own withdrawal ID. Acts as an **idempotency key** — retrying with the same ID returns the existing request instead of creating a duplicate |
| `chainId`              | number | Yes      | Blockchain chain ID                                                                                                                             |
| `tokenAddress`         | string | Yes      | Token contract address. Must be enabled for your vault. Use the zero address for native tokens                                                  |
| `amount`               | string | Yes      | Amount in the token's **smallest units** (e.g. `"5000000"` = 5 USDT at 6 decimals)                                                              |
| `destinationAddress`   | string | Yes      | Address the payout is sent to                                                                                                                   |
| `metadata`             | string | No       | Free-form string (max 1KB), echoed back in webhooks                                                                                             |

#### Example Request

```bash
curl -X POST https://app.makapay.io/api/vault/v1/withdrawals \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_123",
    "externalWithdrawalId": "wd_789",
    "chainId": 137,
    "tokenAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "amount": "5000000",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "metadata": "cashier-session-42"
  }'
```

#### Response

```json
{
  "success": true,
  "error": null,
  "data": {
    "withdrawalId": "abc123",
    "externalWithdrawalId": "wd_789",
    "externalUserId": "user_123",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "amount": "5000000",
    "decimals": 6,
    "tokenAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "tokenSymbol": "USDT",
    "chainId": 137,
    "status": "pending",
    "payoutTxHash": null,
    "rejectionReason": null,
    "metadata": "cashier-session-42",
    "createdAt": 1704067200000,
    "resolvedAt": null,
    "isNew": true
  }
}
```

> **Note:** `isNew` is `false` when the request matched an existing withdrawal by `externalWithdrawalId` (i.e. you retried a request that was already created).

#### Error Responses

| Status | Error                                 | Description                                                                           |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------- |
| 400    | Validation failed                     | A required field is missing or invalid (e.g. the token is not enabled for your vault) |
| 401    | Unauthorized                          | Missing or invalid API key                                                            |
| 501    | SOLANA\_WITHDRAWALS\_NOT\_IMPLEMENTED | Withdrawals are EVM-only for now — Solana withdrawals are not yet available           |

***

### List Withdrawals

List your withdrawal requests, with optional filters. Use this endpoint to reconcile state if your webhook endpoint was down.

```
GET /vault/v1/withdrawals
```

#### Query Parameters

| Parameter              | Type   | Required | Description                                                                               |
| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `status`               | string | No       | Filter by status: `pending`, `approving`, `confirming`, `completed`, `rejected`, `failed` |
| `externalUserId`       | string | No       | Filter by your user ID                                                                    |
| `externalWithdrawalId` | string | No       | Exact lookup by your withdrawal ID                                                        |
| `limit`                | number | No       | Max results (default: 50, max: 100)                                                       |

#### Example Request

```bash
# Withdrawals awaiting approval
curl "https://app.makapay.io/api/vault/v1/withdrawals?status=pending&limit=50" \
  -H "x-api-key: YOUR_API_KEY"

# Look up a specific withdrawal by your own ID
curl "https://app.makapay.io/api/vault/v1/withdrawals?externalWithdrawalId=wd_789" \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "success": true,
  "error": null,
  "data": {
    "withdrawals": [
      {
        "withdrawalId": "abc123",
        "externalWithdrawalId": "wd_789",
        "status": "pending",
        "...": "same fields as the Create Withdrawal Request response"
      }
    ],
    "total": 1
  }
}
```

Each item in `withdrawals` contains the same fields as the [Create Withdrawal Request](#create-withdrawal-request) response.

#### Error Responses

| Status | Error                           | Description                                                |
| ------ | ------------------------------- | ---------------------------------------------------------- |
| 400    | limit must be a positive number | `limit` is not a positive number                           |
| 401    | Unauthorized                    | Missing or invalid API key                                 |
| 404    | Withdrawal not found            | No request matches the `externalWithdrawalId` exact lookup |

***

### Cancel Withdrawal Request

Cancel a withdrawal request (e.g. the player cancelled the withdrawal in your cashier). Only `pending` requests can be cancelled. Cancelling resolves the request as `rejected` with `rejectionReason: "cancelled_by_casino"` and fires a `withdrawal.rejected` webhook.

```
DELETE /vault/v1/withdrawals
```

#### Query Parameters

| Parameter              | Type   | Required | Description                                 |
| ---------------------- | ------ | -------- | ------------------------------------------- |
| `externalWithdrawalId` | string | Yes      | Your withdrawal ID of the request to cancel |

#### Example Request

```bash
curl -X DELETE "https://app.makapay.io/api/vault/v1/withdrawals?externalWithdrawalId=wd_789" \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the updated withdrawal object (same fields as the [Create Withdrawal Request](#create-withdrawal-request) response) with `status: "rejected"` and `rejectionReason: "cancelled_by_casino"`.

#### Error Responses

| Status | Error                                            | Description                                                            |
| ------ | ------------------------------------------------ | ---------------------------------------------------------------------- |
| 400    | externalWithdrawalId query parameter is required | Missing `externalWithdrawalId`                                         |
| 400    | Only pending withdrawals can be cancelled        | The request has already been approved, resolved, or is being processed |
| 401    | Unauthorized                                     | Missing or invalid API key                                             |
| 404    | Withdrawal not found                             | No request matches this `externalWithdrawalId`                         |

***

## Payment Webhook Configuration API

Manage payment webhook settings programmatically via API key. This mirrors the Vault Webhook API but for standard payment notifications.

### `GET /api/v1/webhooks`

Get the current webhook configuration.

**Headers:**

| Header      | Required | Description          |
| ----------- | -------- | -------------------- |
| `x-api-key` | Yes      | Your MakaPay API key |

**Response:**

```json
{
  "success": true,
  "error": null,
  "data": {
    "webhookUrl": "https://example.com/webhook",
    "events": ["payment.completed", "payment.withdrawn"],
    "isActive": true,
    "secretPreview": "whsec_************************abcd1234",
    "createdAt": 1709550000000,
    "updatedAt": 1709550000000
  }
}
```

**curl example:**

```bash
curl -X GET https://app.makapay.io/api/v1/webhooks \
  -H "x-api-key: mk_your_api_key"
```

***

### `PUT /api/v1/webhooks`

Create or update webhook configuration. On first creation, a dedicated webhook secret (`whsec_...`) is generated and returned.

**Headers:**

| Header         | Required | Description          |
| -------------- | -------- | -------------------- |
| `x-api-key`    | Yes      | Your MakaPay API key |
| `Content-Type` | Yes      | `application/json`   |

**Request Body:**

| Field      | Type      | Required | Description                                                                   |
| ---------- | --------- | -------- | ----------------------------------------------------------------------------- |
| `url`      | string    | Yes      | Webhook URL (must be HTTPS)                                                   |
| `events`   | string\[] | No       | Events to subscribe to. Default: `["payment.completed", "payment.withdrawn"]` |
| `isActive` | boolean   | No       | Whether the webhook is active. Default: `true`                                |

**Valid events:**

* `payment.detected` — Expected amount detected before final confirmation (opt-in)
* `payment.completed` — Payment confirmed and funds received
* `payment.withdrawn` — Funds withdrawn to merchant wallet
* `payment.awaiting_gas` — Payment needs gas tank top-up
* `payment.failed` — Payment failed
* `payment.expired` — Payment expired before completion

**Response (creation — includes full secret):**

```json
{
  "success": true,
  "error": null,
  "data": {
    "webhookUrl": "https://example.com/webhook",
    "events": ["payment.completed", "payment.withdrawn"],
    "isActive": true,
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  }
}
```

**Response (update — secret is masked):**

```json
{
  "success": true,
  "error": null,
  "data": {
    "webhookUrl": "https://example.com/webhook-v2",
    "events": ["payment.completed"],
    "isActive": true,
    "secretPreview": "whsec_************************abcd1234"
  }
}
```

**curl example:**

```bash
curl -X PUT https://app.makapay.io/api/v1/webhooks \
  -H "x-api-key: mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["payment.completed", "payment.withdrawn"],
    "isActive": true
  }'
```

***

### `DELETE /api/v1/webhooks`

Remove the webhook configuration entirely.

**Headers:**

| Header      | Required | Description          |
| ----------- | -------- | -------------------- |
| `x-api-key` | Yes      | Your MakaPay API key |

**Response:**

```json
{
  "success": true,
  "error": null,
  "data": { "deleted": true }
}
```

**curl example:**

```bash
curl -X DELETE https://app.makapay.io/api/v1/webhooks \
  -H "x-api-key: mk_your_api_key"
```

***

### `POST /api/v1/webhooks`

Regenerate the webhook signing secret. The old secret is immediately invalidated.

> **Warning:** If you regenerate the secret while webhook deliveries are in the retry queue, those retries will use the **new** secret. Ensure your server is updated to verify with the new secret before triggering a regeneration, or briefly pause the webhook (`isActive: false`) while rotating.

**Headers:**

| Header         | Required | Description          |
| -------------- | -------- | -------------------- |
| `x-api-key`    | Yes      | Your MakaPay API key |
| `Content-Type` | Yes      | `application/json`   |

**Request Body:**

```json
{
  "action": "regenerate-secret"
}
```

**Response:**

```json
{
  "success": true,
  "error": null,
  "data": {
    "secret": "whsec_new_secret_value_here_32chars"
  }
}
```

**curl example:**

```bash
curl -X POST https://app.makapay.io/api/v1/webhooks \
  -H "x-api-key: mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "regenerate-secret"}'
```

***

## SDK (Coming Soon)

Official SDKs for popular languages:

* **JavaScript/TypeScript**: `npm install @makapay/sdk`
* **Python**: `pip install makapay`
* **PHP**: `composer require makapay/sdk`
* **Go**: `go get github.com/makapay/go-sdk`

***

## Changelog

### v2.0.0

* Added persistent Universal USDC settlement profiles (`GET/POST /api/v2/settlement-profiles`).
* Added payer-funded Universal USDC payment intents (`POST /api/v2/payment-intents`) with one address across accepted sources, live Circle fees, Fast/Standard finality, and direct same-chain delivery.
* Added admin-enabled, per-full-API-key CCTP V2 self-relay for HyperEVM with protocol-only Circle fees and no MakaPay service, platform, or gas fees.
* Existing Universal USDC V1 integrations remain backward compatible.

### v1.4.0 (Current)

* Added Vault Withdrawals API — create, list/reconcile, and cancel non-custodial withdrawal requests (`POST` / `GET` / `DELETE /vault/v1/withdrawals`)
* Added withdrawal webhook events to vault webhooks (`withdrawal.requested`, `withdrawal.completed`, `withdrawal.rejected`, `withdrawal.failed`, `withdrawal.*`)

### v1.3.0

* Added Payment Webhook Configuration API — manage payment webhooks via API key
* Dedicated webhook secrets (`whsec_...`) for payment webhooks (separate from API key)
* Event filtering — subscribe only to the payment events you care about
* Backward compatible — existing webhooks without secrets continue working

### v1.2.0

* Added Vault Configuration API — setup, update, and manage vault accounts via API
* Added token management endpoints (add/remove accepted tokens)
* Added webhook management endpoints (create/update/delete/regenerate secret)
* Webhook secrets now use cryptographically secure generation (nanoid)
* Webhook URLs must use HTTPS
* Webhook secrets are masked in read responses (full secret only on create/regenerate)
* Added Arbitrum One (Chain ID: 42161) to supported networks

### v1.1.0

* Added public `GET /tokens/price` endpoint (Alchemy + TrustedOracle waterfall)
* Added public `GET /tokens/metadata` endpoint (token name, symbol, decimals, logo)
* Added public `GET /oracle/price` endpoint (direct TrustedOracle lookup)
* Added native token support (ETH, BNB, MATIC) as selectable payment tokens
* Added Base network (Chain ID: 8453) to supported networks table
* Updated supported tokens tables with native tokens and token types

### v1.0.0

* Initial API release
* Payment creation endpoint
* Balance endpoint
* Webhook support


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.makapay.io/developers/api-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
