Payouts

Manage payouts

List payouts

get

/api/v1/payouts

Returns all payouts.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Query parameters

pagenumber · min: 1Optional

Page number (1-based)

Default: 1Example: 1

sizenumber · min: 1 · max: 100Optional

Number of items per page

Default: 10Example: 10

searchstringOptional

Search term for payout reference (system or client reference), id, or txHash (for crypto)

Example: PAY-123456

statusstring · enumOptional

Filter by payout status

Example: successPossible values:

recipientIdstringOptional

Filter by payout recipient.

Example: b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11

methodstring · enumOptional

Filter by payout method.

Example: cryptoPossible values:

currencystring · enumOptional

Filter by payout currency.

Example: NGNPossible values:

chainstring · enumOptional

Filter by blockchain. Only crypto payouts move on a blockchain, so this excludes fiat payouts from the results.

Example: tronPossible values:

Responses

200Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

401

Unauthorized

get/api/v1/payouts

GET /api/v1/payouts HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "reference": "PAY-ABC123DEF456",
      "method": "crypto",
      "status": "success",
      "amount": "100.00",
      "fee": "1.50",
      "total": "101.50",
      "currency": "USDT",
      "conversion": {
        "fromCurrency": "USDT",
        "toCurrency": "KES",
        "sourceAmount": "77.60",
        "targetAmount": "10000.00",
        "rate": "128.87"
      },
      "narration": "Manual merchant payout",
      "recipient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "crypto_address",
        "details": {
          "chain": "tron",
          "address": "TF6yMCJqFcT6wFFutxVmRocKgJFD5imKUT"
        }
      },
      "channel": "API",
      "txHash": "0x1234567890abcdef1234567890abcdef12345678",
      "failureReason": null,
      "completedAt": "2024-01-01T12:05:00.000Z",
      "createdAt": "2024-01-01T12:00:00.000Z",
      "updatedAt": "2024-01-01T12:05:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "size": 10,
    "total": 42,
    "totalPages": 5
  }
}

Initiate payout

post

/api/v1/payouts

Initiates a payout to a recipient. Requests authenticated with an API key never need a one-time code. Dashboard requests need a one-time code unless the recipient is trusted.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Body

currencystringRequired

Currency the recipient receives. Local fiat: NGN. Crypto: the asset (USDT/USDC). Cross-border: KES/GHS, funded from the stablecoin balance in sourceCurrency.

Example: NGN

sourceCurrencystring · enumOptional

Stablecoin balance to debit (USDT or USDC), for a cross-border payout where the recipient is paid in a different currency. Omit for local fiat and crypto payouts, which debit the balance in currency.

Example: USDTPossible values:

quoteIdstringOptional

For a cross-border payout, the quoteId from POST /payouts/cross-border/quote. Pass it to pay exactly the quoted price. Quotes expire after two minutes; omit it to price at the current rate.

Example: cbq_123e4567-e89b-12d3-a456-426614174000

amountstringOptional

Amount to pay out, in currency. For a cross-border payout this is the amount the recipient receives, and it is not needed when quoteId is given: the quote already fixes it.

Example: 5000.00

recipientIdstringRequired

Payout receipient Id

Example: 123e4567-e89b-12d3-a456-426614174000

narrationstringOptional

Optional narration/description for the payout

Example: Manual withdrawal - Week 45

referencestringOptional

Optional idempotency reference for your request. If omitted, we generate a reference for you.

Example: CLIENT-REF-12345

webhookUrlstringOptional

Optional URL to receive webhook notifications for this payout (must be HTTPS). Overrides your dashboard webhook URL for this payout only.

Example: https://example.com/webhooks

Responses

201

Payout initialized successfully

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

400

Bad request - validation error, insufficient balance, daily limit exceeded, or missing one-time code (not required when the recipient is trusted)

404

Recipient (bank account or wallet address) not found

500

Internal server error - payout processing failed

post/api/v1/payouts

POST /api/v1/payouts HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 284

{
  "currency": "NGN",
  "sourceCurrency": "USDT",
  "quoteId": "cbq_123e4567-e89b-12d3-a456-426614174000",
  "amount": "5000.00",
  "recipientId": "123e4567-e89b-12d3-a456-426614174000",
  "narration": "Manual withdrawal - Week 45",
  "reference": "CLIENT-REF-12345",
  "webhookUrl": "https://example.com/webhooks"
}

{
  "success": true,
  "message": "Crypto payout initialized successfully",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "PAY-ABC123DEF456",
    "method": "crypto",
    "status": "processing",
    "amount": "100.00",
    "fee": "1.00",
    "total": "101.00",
    "currency": "USDT",
    "conversion": null,
    "narration": "Manual merchant payout",
    "recipient": {
      "id": "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454",
      "type": "crypto_address",
      "details": {
        "chain": "tron",
        "address": "TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"
      }
    },
    "channel": "API",
    "txHash": null,
    "failureReason": null,
    "completedAt": null,
    "createdAt": "2026-07-01T12:00:00.000Z",
    "updatedAt": "2026-07-01T12:00:00.000Z"
  }
}

Quote a cross-border payout

post

/api/v1/payouts/cross-border/quote

Returns the fee and conversion for a cross-border payout, priced by the amount to pay from a balance (sourceAmount). Call this before creating the payout to show the cost. Cross-border payouts are available to verified businesses.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Body

currencystring · enumRequired

Currency the recipient receives.

Example: KESPossible values:

sourceCurrencystring · enumRequired

Stablecoin balance the payout is funded from and debited in.

Example: USDTPossible values:

sourceAmountstringRequired

Amount to pay from the balance, in sourceCurrency. The amount the recipient receives is derived from it.

Example: 78.00

Responses

200Success

application/json

idstringRequired

Quote id. Pass it as quoteId to POST /payouts to pay exactly this price before it expires.

Example: cbq_123e4567-e89b-12d3-a456-426614174000

feestringRequired

Flat fee, in conversion.fromCurrency.

Example: 1.50

totalstringRequired

Total debited from the balance: conversion.sourceAmount plus fee, in conversion.fromCurrency.

Example: 79.10

expiresAtstringRequired

When this quote expires. After this time, request a new quote.

Example: 2026-07-22T12:02:00.000Z

post/api/v1/payouts/cross-border/quote

POST /api/v1/payouts/cross-border/quote HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "currency": "KES",
  "sourceCurrency": "USDT",
  "sourceAmount": "78.00"
}

200Success

{
  "id": "cbq_123e4567-e89b-12d3-a456-426614174000",
  "conversion": {
    "fromCurrency": "USDT",
    "toCurrency": "KES",
    "sourceAmount": "77.60",
    "targetAmount": "10000.00",
    "rate": "128.87"
  },
  "fee": "1.50",
  "total": "79.10",
  "expiresAt": "2026-07-22T12:02:00.000Z"
}

Retrieve payout

get

/api/v1/payouts/{id}

Returns the payout for the given ID.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters

idstringRequired

Responses

200

Payout retrieved successfully

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

401

Unauthorized

404

Payout not found

get/api/v1/payouts/{id}

GET /api/v1/payouts/{id} HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "Payout retrieved successfully",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "PAY-ABC123DEF456",
    "method": "crypto",
    "status": "success",
    "amount": "100.00",
    "fee": "1.00",
    "total": "101.00",
    "currency": "USDT",
    "conversion": null,
    "narration": "Manual merchant payout",
    "recipient": {
      "id": "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454",
      "type": "crypto_address",
      "details": {
        "chain": "tron",
        "address": "TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"
      }
    },
    "channel": "API",
    "txHash": "b9f4a2d6e8c1073a5f4e2b8d9c0a1f3e6d5b4a2c8e7f9d0b1a3c5e7f9b2d4a6c",
    "failureReason": null,
    "completedAt": "2026-07-01T12:05:00.000Z",
    "createdAt": "2026-07-01T12:00:00.000Z",
    "updatedAt": "2026-07-01T12:05:00.000Z"
  }
}

Retrieve all payout fees

get

/api/v1/payouts/fees

Returns fiat, cross-border, and crypto payout fees across every supported currency, corridor, chain, and asset.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Responses

200Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Payout fees retrieved successfully

401

Unauthorized

500

Internal server error - Unable to calculate fees

get/api/v1/payouts/fees

GET /api/v1/payouts/fees HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "Payout fees retrieved successfully",
  "data": {
    "fiat": {
      "NGN": {
        "BankTransfer": "50.00"
      }
    },
    "crossBorder": {
      "KES": {
        "MobileMoney": "2.00"
      },
      "GHS": {
        "MobileMoney": "2.00"
      }
    },
    "crypto": {
      "USDT": {
        "bsc": "0.50",
        "tron": "1.00",
        "solana": "0.50"
      },
      "USDC": {
        "solana": "0.50"
      }
    }
  }
}

PreviousDeposits

NextPayout Recipients

Last updated 1 hour ago

Was this helpful?