Create a bulk transfer

Submit multiple transfer items in one request. Each item is stored independently, so a failure on one beneficiary does not hide the result of the other items.

Endpoint

POST /api/bulk-payouts

Requires X-API-Key authentication.

Request body

{
  "currency": "XAF",
  "items": [
    {
      "name": "John Doe",
      "phone": "+237690000000",
      "amount_minor": 2000,
      "service_mobile_code": "MTN-CM",
      "external_reference": "ORDER-1001"
    },
    {
      "name": "Jane Doe",
      "phone": "+237650000000",
      "amount_minor": 3500,
      "service_mobile_code": "ORANGE-CM",
      "external_reference": "ORDER-1002"
    }
  ]
}

Fields

FieldTypeRequiredDescription
currencystringYesBatch currency, for example XAF.
itemsarrayYesAt least one transfer item.
items[].namestringYesBeneficiary name.
items[].phonestringYesBeneficiary phone number.
items[].amount_minorintegerYesAmount in XAF. Each value must be between 500 and 1,000,000 and be a multiple of 50.
items[].service_mobile_codestringYesA mobile-service code_prefix.
items[].beneficiary_idstringNoExisting beneficiary identifier.
items[].external_referencestringNoYour own idempotency or reconciliation reference.

Example request

curl -X POST <SANDBOX_API_URL>/bulk-payouts \
  -H 'X-API-Key: <your_sandbox_api_key>' \
  -H 'Content-Type: application/json' \
  -d @bulk-transfer.json

Response

{
  "batch": {
    "id": "batch_123",
    "organisation_id": "organisation_123",
    "reference": "BATCH-1731493800000",
    "status": "PENDING",
    "total_items": 2,
    "succeeded_items": 0,
    "failed_items": 0,
    "createdAt": "2026-11-13T10:30:00.000Z"
  }
}

The batch is asynchronous. Use the returned batch reference and the transfer listing to reconcile individual results.

Errors

  • 400 — empty batch, invalid item, or insufficient balance;
  • 401 — missing or invalid API key;
  • 500 — unexpected server error.