Skip to main content
POST
/
v1
/
transfers
/
batch
Create batch transfer
curl --request POST \
  --url https://api.adullam.dev/v1/transfers/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "transfers": [
    {
      "amount": 50000,
      "recipient_phone": "+22507123456",
      "channel": "mtnCI",
      "reference": "EMP_001",
      "description": "Salary payment"
    }
  ],
  "description": "Monthly salary batch",
  "reference": "SALARY_JAN_2024"
}
'
{
  "id": "batch_abc123",
  "status": "processing",
  "total_amount": 125000,
  "total_count": 2,
  "processed_count": 0,
  "successful_count": 0,
  "failed_count": 0,
  "pending_count": 2,
  "description": "Monthly salary batch",
  "reference": "SALARY_JAN_2024",
  "total_fees": 100,
  "transfers": [
    {
      "id": "txf_abc123",
      "status": "processing",
      "amount": 10000,
      "currency": "XOF",
      "recipient_phone": "+22507123456",
      "recipient_name": "DIALLO IBRAHIM",
      "channel": "mtnCI",
      "description": "Salary payment",
      "reference": "PAY_001",
      "ussd_reference": "MP240115.1032.T98765",
      "fees": 50,
      "metadata": {
        "employee_id": "EMP_123"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "completed_at": null,
      "failure_reason": null
    }
  ],
  "created_at": "2024-01-15T10:00:00Z",
  "started_at": null,
  "completed_at": null
}

​
Create Batch Transfer

Creating a batch transfer enables you to process multiple transfers in one request, ideal for bulk payouts. Use the Create Batch Transfer API to submit an array of transfer instructions, each with its own recipient and amount.

Authorizations

​
Authorization
string
header
required

Use the access token obtained from /v1/auth/token

Headers

​
Idempotency-Key
string<uuid>
required

UUID for idempotent requests

Body

application/json
​
transfers
object[]
required
Required array length: 2 - 1000 elements
​
description
string
Maximum string length: 200
Example:

"Monthly salary batch"

​
reference
string
Maximum string length: 100
Example:

"SALARY_JAN_2024"

Response

Batch transfer created

​
id
string
Example:

"batch_abc123"

​
status
enum<string>
Available options:
pending,
processing,
completed,
failed,
partial_completed
Example:

"processing"

​
total_amount
integer
Example:

125000

​
total_count
integer
Example:

2

​
processed_count
integer
Example:

0

​
successful_count
integer
Example:

0

​
failed_count
integer
Example:

0

​
pending_count
integer
Example:

2

​
description
string
Example:

"Monthly salary batch"

​
reference
string
Example:

"SALARY_JAN_2024"

​
total_fees
integer
Example:

100

​
transfers
object[]
​
created_at
string<date-time>
Example:

"2024-01-15T10:00:00Z"

​
started_at
string<date-time> | null
Example:

null

​
completed_at
string<date-time> | null
Example:

null