Skip to navigation
Payouts

Getting Started with Payouts

Send payouts to banks and mobile wallets

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 and mobile wallets 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 draw on your CrissCross balance; 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 status & history: GET https://api.crisscross.money/v1/payout (list) and GET https://api.crisscross.money/v1/payout/{transactionId} (single payout)

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 client_id and client_secret, 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 '{
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "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 or mobile 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 on your CrissCross balance. Before sending payouts, make sure you have sufficient funds in the payout currency.

  1. Fund your account: Use the Exchange Deposits endpoints to add funds in supported currencies.
  2. Check balances: Use GET /v1/balance to confirm available funds — it returns one entry per processor configuration with balance, availableBalance, and currency.
  3. Convert if needed: Use the Exchange Trading endpoints to convert into the payout currency (e.g., NGN, KES).
  4. Payout: Create single or bulk payouts once the target balance is available.

For endpoint details, see Exchange Funding 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 the following currencies:

  • NGN - Nigerian Naira
  • XOF - West African CFA Franc
  • XAF - Central African CFA Franc
  • GHS - Ghanaian Cedi
  • KES - Kenyan Shilling
  • ZAR - South African Rand
  • TZS - Tanzanian Shilling
  • UGX - Ugandan Shilling
  • EGP - Egyptian Pound

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

Recipient Types

The Payouts API supports four recipient types:

  • Bank Account (bank_account): Send funds directly to bank accounts
  • Mobile Wallet (mobile_money): Send funds to mobile money wallets (MoMo)
  • Cash (cash): Cash pickup, where available
  • Institution Wallet (institution_wallet): Send funds to a wallet held at a financial institution

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

For full destination details and required vs optional fields by recipient type, see Bank Transfers and Mobile Wallet; for cash and institution_wallet, see the API reference. 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; must be unique per payout — reused references are rejected (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, TZS, UGX, ZAR, EGP — availability depends on the processors configured on your account)
  • paymentMethodId: "banktransfer", "mobilemoney", "cash", or "institutionwallet" (note: no underscore, unlike the matching recipient.type)
  • paymentLocation: 3-letter ISO country code (e.g., NGA, KEN, EGY)
  • Either recipient or payoutBeneficiaryId (see Specifying the Destination below)
  • sender: Sender details for KYT/KYC screening — fullName, identity (document type, e.g. passport or nationalId), and identityNumber are required for all payouts; some destinations require additional fields (see the market pages)

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.

Specifying the Destination

Every payout needs a destination. You can supply it in one of two ways — pick one, not both:

  • Inline recipient — supply the recipient’s account details on every payout call. Fastest for one-off payouts; details are validated synchronously when the payout is initiated.
  • payoutBeneficiaryId — register the recipient once via POST /v1/payout-beneficiaries, wait for it to reach status: approved, then reference the returned payoutBeneficiaryId on every subsequent payout. Verification and AML pre-screening happen up front (before any money is debited), the per-call payload is smaller, and you can’t accidentally let recipient details drift between repeat payouts to the same person.

For the full registration, lifecycle, and signal flow, see Payout Beneficiaries.

Amount Format

Amounts are specified in minor units — the currency’s smallest unit, per its ISO 4217 exponent. For example:

minorAmountCurrencyMinor unitActual amount
10000NGN2 decimal places100.00 NGN
5000KES2 decimal places50.00 KES
5000XOFnone — whole units5,000 XOF

Important: The minorAmount field is an integer, not a float. Most currencies have 2 decimal places, but not all: XOF, XAF, UGX, RWF, BIF, and GNF have none, so no multiplication applies.

Idempotency

Each payout must use a merchantReference that is unique within your merchant account. Reusing a reference from a previous payout causes the request to be rejected with a DUPLICATE_REFERENCE error (HTTP 409 Conflict) — the API does not create a second payout and does not replay the original. This prevents accidental duplicate payouts when a request is retried due to network issues or timeouts. Uniqueness is enforced per merchant account and does not expire.

If you’re unsure whether a request succeeded, retry it with the same merchantReference: a 409 Conflict means the original payout was already accepted (look it up via the history endpoints), while any other error means it is safe to retry.

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 client_id and client_secret (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.

Before going live, test your integration in the sandbox. Start with Your First Payout.

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 Webhook Events for the event types.
  • Understanding Responses: See Understanding Responses for how success and error responses work, including error body shape and handling.