Payouts

Getting Started with Payouts

Send payouts to banks, wallets, or stablecoin addresses

The CrissCross Payouts API enables you to send local payouts to banks or wallets in 20+ African markets through one API. Get the most competitive FX rates, transparent pricing, and reconciliation. Whether handling individual transactions or large-volume disbursements, the Payouts API provides the flexibility to manage payouts reliably and efficiently.

When to use Payouts vs Exchange withdrawals

  • Use the Payouts API when you want to send funds to third-party recipients (e.g. suppliers, customers, employees, sellers). Payouts are for disbursements to bank accounts, mobile wallets, or stablecoin addresses in supported markets.
  • Use the Exchange Withdrawals endpoint when you want to withdraw your own balance from CrissCross to your own bank account or crypto wallet (moving funds out of your CrissCross account). Exchange withdrawals are for moving your funds to an account you control.

Both use your Exchange account balances as the source of funds; the difference is the destination (your own account vs someone else’s).

API Base URL

All payout endpoints are available at:

https://api.crisscross.money/v1

For example:

  • Single payout: POST https://api.crisscross.money/v1/payouts
  • Bulk payouts: POST https://api.crisscross.money/v1/payouts/bulk
  • Payout history: GET https://api.crisscross.money/v1/payouts/history

Authentication

All payout API requests require OAuth 2.0 authentication using Bearer tokens. You obtain an access token by calling the Authentication endpoint with your clientId and clientSecret, then include the token in the Authorization header on subsequent requests.

Quick Start:

  1. Get an access token:

    $curl --request POST 'https://api.crisscross.money/v1/auth/oauth2/token' \
    >  --header 'Content-Type: application/json' \
    >  --data-raw '{
    >    "clientId": "YOUR_CLIENT_ID",
    >    "clientSecret": "YOUR_CLIENT_SECRET"
    >  }'

  2. Use the token in payout requests:

    $curl --request POST 'https://api.crisscross.money/v1/payouts' \
    >  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    >  --header 'Content-Type: application/json' \
    >  --data-raw '{ ... }'

For detailed authentication instructions, including token expiration and best practices, see the Authentication guide.

Key Features

  • Single Payouts: Send a one-time payout to a recipient’s bank account, mobile wallet, or crypto wallet.
  • Bulk Payouts: Schedule multiple payouts in a single request, ideal for handling larger batches of disbursements.
  • Competitive FX Rates: Access the most competitive FX rates on every payout transaction.
  • 20+ Market Coverage: Send payouts across 20+ African markets through a single API.
  • Transparent Pricing: Clear, upfront pricing with no hidden fees.

Workflow

  • Check Balance: Use the Balances Endpoint to confirm sufficient funds in the payout currency.
  • Top-up Account (if needed): Convert between supported fiat currencies using the Trading endpoint.
  • Initiate Payout: Send funds using either the single or bulk payout endpoints, depending on your needs.
  • Track Payout History: Use the Payout History Endpoint to monitor and review payout transactions, with options to filter by date range or specific payout ID.

The Payouts API is built for businesses that need to move money across regions reliably, whether for operational payments, customer disbursements, or payroll.

Funding Your Payout Balance

Payouts draw from your Exchange account balances. Before sending payouts, make sure you have sufficient funds in the payout currency (fiat or stablecoin).

  1. Fund your account: Use the Exchange Deposits endpoints to add funds in supported fiat or crypto currencies.
  2. Check balances: Use the Exchange Balances endpoint to confirm available funds.
  3. Convert if needed: Use the Exchange Trading endpoints to convert into the payout currency (e.g., NGN, KES, USDT, USDC).
  4. Payout: Create single or bulk payouts once the target balance is available.

For endpoint details, see Exchange Accounts and Exchange Trading.

Use Cases

  • Operational Payments: Pay suppliers, vendors, or service providers
  • Customer Disbursements: Send refunds, rewards, or payouts to customers
  • Payroll: Distribute salaries or wages to employees
  • Marketplace Payouts: Pay out earnings to sellers or service providers

Supported Currencies

Payouts are supported in Fiat Currencies and Stablecoins:

  • NGN - Nigerian Naira
  • XOF - West African CFA Franc
  • XAF - Central African CFA Franc
  • GHS - Ghanaian Cedi
  • KES - Kenyan Shilling
  • ZAR - South African Rand
  • AED - UAE Dirham
  • EGP - Egyptian Pound

Stablecoins

  • USDT - Tether (ERC20, TRC20)
  • USDC - USD Coin (ERC20, TRC20)

Note: If you need to convert between fiat currencies or into stablecoins before paying out, use the Trading API first.

Recipient Types

The Payouts API supports three recipient types:

  • Bank Account (bank_account): Send funds directly to bank accounts
  • Mobile Wallet (mobile_money): Send funds to mobile money wallets (MoMo)
  • Crypto Wallet (crypto_wallet): Send funds to stablecoin wallets (USDT/USDC)

Bank Account Recipients

For bank account payouts, you’ll need:

  • type: Set to "bank_account"
  • accountNumber: The recipient’s bank account number
  • bankCode: Bank identifier code (e.g., sort code, routing number)
  • accountHolderName: Name on the bank account
  • country: 3-letter ISO country code (e.g., NGA, EGY)
  • phoneNumber: Optional phone number in international format

Mobile Wallet Recipients

For mobile wallet payouts, you’ll need:

  • type: Set to "mobile_money"
  • phoneNumber: Mobile money MSISDN in international format
  • country: 3-letter ISO country code (e.g., KEN, CIV, SEN)
  • operator: Mobile money operator (e.g., mpesa, mtn, orange, airtel, moov, wave)
  • name: Optional full name of the recipient

Crypto Wallet Recipients

For stablecoin payouts, you’ll need:

  • type: Set to "crypto_wallet"
  • address: Destination wallet address
  • network: Transfer network (ERC20 or TRC20)
  • memo: Optional memo or tag (required by some wallets)

For full destination details and required vs optional fields by recipient type, see Bank Transfers, Mobile Wallet, and Stablecoin Payouts. Which destinations and rails are supported is listed in Supported Destinations.

Request Structure

All payout requests require:

  • merchantId: Your merchant identifier
  • merchantReference: Your internal reference for tracking (used for idempotency - see Idempotency below)
  • destinationValue: Object containing:
    • minorAmount: Amount in minor units (integer, e.g., 10000 = 100.00 NGN)
    • currency: Currency code (NGN, XOF, XAF, GHS, KES, ZAR, AED, EGP, USDT, USDC)
  • paymentMethodId: "banktransfer", "mobilemoney", or "crypto"
  • paymentLocation: 3-letter ISO country code (e.g., NGA, KEN, EGY)
  • recipient: Object containing recipient details (structure depends on paymentMethodId)

Optional fields:

  • attributes: Optional key-value map for additional payout metadata or provider-specific options (e.g. clearing preferences). Pass an empty object {} if not needed. See the API reference for supported keys per destination.
  • sender: Sender details (required for some destinations, includes KYC fields)

Amount Format

Amounts are specified in minor units (the smallest currency unit, like cents). For example:

  • 10000 minorAmount = 100.00 NGN (Nigerian Naira)
  • 5000 minorAmount = 50.00 KES (Kenyan Shillings)
  • 10000 minorAmount = 100.00 EGP (Egyptian Pounds)
  • 1000000 minorAmount = 1.000000 USDT

Important: The minorAmount field is an integer, not a float. Fiat currencies use 2 decimal places (multiply by 100). USDT/USDC use 6 decimal places (multiply by 1,000,000).

Idempotency

The merchantReference field enables idempotency for payout requests. If you send a payout request with a merchantReference that was used in a previous successful request, the API will return the original payout instead of creating a duplicate. This helps prevent accidental duplicate payouts if a request is retried due to network issues or timeouts.

Best practice: Use unique, meaningful references for each payout (e.g., PAYOUT-2024-001, REFUND-ORDER-12345). Store the reference along with the transaction ID for reconciliation.

Getting Started

  1. Authenticate: Obtain an OAuth 2.0 access token using your clientId and clientSecret (see Authentication above).

  2. Check Your Balance: Ensure you have sufficient funds in the payout currency using the Accounts API.

  3. Convert Currency (if needed): If you need to convert from a major currency to a minor currency or stablecoin, use the Trading API first.

  4. Create a Payout:

    • For single payouts: POST https://api.crisscross.money/v1/payouts - See Single Payouts
    • For bulk payouts: POST https://api.crisscross.money/v1/payouts/bulk - See Bulk Payouts

  5. Track Payouts: Use the Payout History endpoints to monitor payout status, or set up webhooks for real-time status updates.

Additional Resources

  • Rate Limiting: The API enforces rate limits to ensure system stability. See Rate Limiting for details and best practices.
  • Webhooks: Receive real-time notifications about payout status changes. See Webhooks for setup and event types.
  • Understanding Responses: See Understanding Responses for how success and error responses work, including error body shape and handling.