Bulk Payouts

Bulk payouts allow you to send funds to multiple recipients in a single API call. This is ideal for processing large batches of disbursements efficiently, such as payroll, marketplace payouts, or mass customer disbursements.

When to Use Bulk Payouts

• Processing payroll for multiple employees
• Marketplace seller payouts
• Mass customer disbursements
• Regular scheduled payments
• High-volume operations

Creating Bulk Payouts

A bulk payout request can include multiple payouts in a single batch. Each payout in the batch follows the same structure as a single payout:

• merchantId: Your merchant identifier
• merchantReference: Your internal reference for tracking and idempotency
• destinationValue: Object with minorAmount (integer) and currency
• paymentMethodId: "banktransfer", "mobilemoney", or "crypto"
• paymentLocation: 3-letter ISO country code
• recipient: Recipient details (structure depends on paymentMethodId)
• sender (optional): Sender details with KYC fields (required for some destinations)
• attributes (optional): Additional payout attributes

Note: Amounts are specified in minor units (integer). Fiat currencies use 2 decimal places; USDT/USDC use 6. See Single Payouts for details.

Request Structure

1
{
2
  "payouts": [
3
    {
4
      "merchantId": "your-merchant-id",
5
      "merchantReference": "PAYOUT-001",
6
      "destinationValue": {
7
        "minorAmount": 1000000,
8
        "currency": "NGN"
9
      },
10
      "paymentMethodId": "banktransfer",
11
      "paymentLocation": "NGA",
12
      "recipient": {
13
        "type": "bank_account",
14
        "accountNumber": "0123456789",
15
        "bankCode": "044",
16
        "accountHolderName": "John Doe",
17
        "country": "NGA"
18
      },
19
      "attributes": {}
20
    },
21
    {
22
      "merchantId": "your-merchant-id",
23
      "merchantReference": "PAYOUT-002",
24
      "destinationValue": {
25
        "minorAmount": 500000,
26
        "currency": "KES"
27
      },
28
      "paymentMethodId": "mobilemoney",
29
      "paymentLocation": "KEN",
30
      "recipient": {
31
        "type": "mobile_money",
32
        "phoneNumber": "254712345678",
33
        "country": "KEN",
34
        "operator": "mpesa",
35
        "name": "Jane Smith"
36
      },
37
      "attributes": {}
38
    },
39
    {
40
      "merchantId": "your-merchant-id",
41
      "merchantReference": "PAYOUT-003",
42
      "destinationValue": {
43
        "minorAmount": 2500000,
44
        "currency": "USDC"
45
      },
46
      "paymentMethodId": "crypto",
47
      "paymentLocation": "USA",
48
      "recipient": {
49
        "type": "crypto_wallet",
50
        "address": "0x1111222233334444555566667777888899990000",
51
        "network": "ERC20"
52
      },
53
      "attributes": {}
54
    }
55
  ]
56
}

Note: minorAmount: 1000000 = 10,000.00 NGN, minorAmount: 500000 = 5,000.00 KES, minorAmount: 2500000 = 2.500000 USDC.

Response Structure

Bulk payouts are processed asynchronously. The create request returns a 202 Accepted with a batch ID and monitor URL.

1
{
2
  "message": "Batch accepted for processing",
3
  "batchId": "batch_1234567890",
4
  "monitorUrl": "https://api.crisscross.money/v1/payouts/bulk/batch_1234567890"
5
}

Response fields:

• message: Status message confirming the batch was accepted
• batchId: Identifier for the batch
• monitorUrl: URL to poll for batch status

Benefits

• Efficiency: Process multiple payouts in one API call
• Performance: Reduced API calls and faster processing
• Reliability: Batch processing with status tracking for each payout
• Cost-effective: Lower overhead for high-volume operations
• Partial Success Handling: Individual payouts can succeed or fail independently

Example Use Cases

• Payroll: Distribute salaries to all employees at once
• Marketplace Payouts: Pay out earnings to multiple sellers
• Mass Refunds: Process refunds for multiple customers
• Regular Disbursements: Scheduled payments to multiple recipients

Handling Partial Failures

When processing bulk payouts, individual payouts may succeed or fail independently. Use the monitorUrl to poll for batch status and outcomes, or consume updates via webhooks.

Error Handling

If the entire bulk request fails (e.g., invalid request structure, authentication error), the API returns an HTTP 400, 401, or 422 with an error object:

1
{
2
  "error": {
3
    "code": "INVALID_REQUEST",
4
    "message": "Invalid bulk payout request structure"
5
  }
6
}

If the request succeeds, the response is HTTP 202 with a batchId and monitorUrl. Use the monitor URL or webhooks to check individual outcomes.

Best Practices

• Validate all recipient details before creating bulk payouts
• Use unique, meaningful references for each payout (enables idempotency and easy tracking)
• Monitor batch status and individual payout statuses through history endpoints or webhooks
• Implement retry logic for failed payouts (with corrected recipient details)
• Keep batch sizes manageable and consider splitting very large batches
• Check the successful and failed counts in the response
• Review individual payout status and failureReason fields for failed payouts
• Store payout IDs and references for reconciliation and tracking

For detailed API documentation, see the Payouts API Reference.