Send up to 100 payouts at once

Sends up to 100 payouts in one request. Each item has the same fields as POST /v1/payouts and is accepted or refused on its own, so one refusal does not stop the others. Your limits apply to each item as if it were sent alone.

If the batch itself is malformed (no items, more than 100, an invalid item or a reference repeated within the batch), the whole batch is refused with 400 and nothing is sent.

A 200 lists each item with its status: 202 and the payout when it was accepted, otherwise an error with the same codes a single payout would get, such as daily_limit_exceeded. Read each payout back with GET /v1/payouts/{reference}; webhooks arrive for each payout, not for the batch.

Send a required Idempotency-Key header. After a timeout or a 5xx, retry with the same key and body: accepted items are not sent again. Requires the disbursements.write permission.

POST/v1/payout-batches

Authorization

AuthorizationBearer token (JWT) · headerrequired

A token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.

Header parameters

Idempotency-Keystringrequired

A unique value you generate for this attempt, at most 255 characters. Send the same value when you retry the same request: it is answered once, however many times you send it. Reusing a value with a different body is refused with 409 idempotency_key_reused.

min length 1 · max length 255

Request body

requiredapplication/json

referencestringrequired

Your reference for the batch, unique for each batch.

matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

itemsPayoutRequest[]required

The payouts. Each reference must be unique within the batch.

min items 1 · max items 100

Show properties

Array of PayoutRequest

referencestringrequired

Your own identifier for this request, 1 to 64 letters, digits, underscores or hyphens, starting with a letter or digit. It must be unique for each request you start.

matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

amountstringrequired

The amount to send. A decimal string in major units.

currencystringrequired

Three-letter currency code.

matches ^[A-Z]{3}$

providerstringrequired

The mobile money or bank provider, for example mtn, telecel or calbank. List what your account can use with GET /v1/payment-methods.

destinationobjectrequired

Show properties

typestringrequired

What kind of account the recipient is.

Allowed:msisdnaccountcard

valuestringrequired

The mobile money number, account number or card reference.

notestring

Optional text stored with the record. At most 50 characters, no control characters. It is not sent to the provider.

max length 50

Responses

200

The batch was received. Each item has its own outcome.

batchIdstringrequired

The batch's id.

referencestringrequired

Your reference for the batch.

itemsobject[]required

One entry per item, in the order sent.

Show properties

Array of object

referencestringrequired

The item's payout reference.

statusintegerrequired

202 when the payout was accepted, otherwise the status a single payout would have been refused with.

payoutPayout

Show properties

referencestringrequired

The reference you chose.

amountstring

The requested amount. A decimal string in major units.

currencystring

Three-letter currency code.

matches ^[A-Z]{3}$

statusstringrequired

Where the request stands, reported as it is: accepted, dispatching, in_review, held, delivered, failed or refunded. Others can appear, so do not treat this list as closed.

providerstring

The provider used.

feestring

The fee charged. Left out when none was recorded. A decimal string in major units.

feeBearerstring

Who pays the fee. initiator: the party who starts the request pays the amount plus the fee, and the recipient gets the full amount. non_initiator: the fee comes out of what the recipient gets.

Allowed:initiatornon_initiator

payerAmountstring

What the payer is charged. Left out when the fee bearer is not known. A decimal string in major units.

recipientAmountstring

What the recipient receives. Left out when the fee bearer is not known. A decimal string in major units.

notestring

The note you sent.

failureReasonstring

The provider's own reason when the request failed. Left out otherwise.

createdAtstring<date-time>

completedAtstring<date-time>

When it reached its final status. Left out while it is still moving, and on older movements where the time was not recorded.

channelstring

How it was started. api is the only value today.

Allowed:api

reconciliationReconciliation

What the platform's check against the provider concluded.

Show properties

statusstringrequired

unchecked (not checked yet), matched (the provider agrees) or mismatched (the provider disagrees; the platform is looking into it).

Allowed:uncheckedmatchedmismatched

checkedAtstring<date-time>

When it was last checked. Left out until it has been.

parentLineageLink

The movement this one undoes, when it is a reversal. Left out otherwise.

Show properties

typestringrequired

What kind of movement it is.

Allowed:collectionpayoutwallet_transfer

referencestringrequired

Its reference.

compensationLineageLink

The reversal recorded against this movement. Left out when there is none.

Show properties

typestringrequired

What kind of movement it is.

Allowed:collectionpayoutwallet_transfer

referencestringrequired

Its reference.

errorobject

Why this item was refused.

Show properties

codestringrequired

messagestringrequired

400

The request is not valid. message says which field.

errorobjectrequired

Show properties

codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

401

The token is missing, expired or not valid. Get a new one from the token endpoint.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

403

The request was understood and refused. Common causes: the token is not an API credential's (forbidden); the credential is for the other environment (environment_mismatch); it does not have the permission this operation needs (forbidden); a limit was reached (limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded); or iSmartPay has suspended or deactivated the business (business_suspended, business_deactivated). A suspended business's API credentials stop exchanging for tokens, so a request made with a token issued just before the suspension is refused with business_suspended.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

409

idempotency_key_reused: the key was used before with a different body. request_in_flight: a request with this key is still being processed, so retry shortly. duplicate_reference: the reference is already used by a different request, so choose a new one; sending the same body again under a new key replays the first answer.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

429

Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

500

Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

502

A service behind the API did not answer usably. If the request was a POST, retry with the same Idempotency-Key and body. A party lookup the provider rejects is provider_error.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

503

The API is temporarily unable to tell which environment it serves (environment_unknown), utility purchases are not available right now (utilities_unavailable), a settlement destination could not be name-checked just now (destination_verification_unavailable; retry the same request), or hosted checkout is not set up on this deployment (checkout_unavailable). Retry shortly, except for checkout_unavailable, which lasts until the deployment is configured.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

504

The request took too long. If it was a POST, its outcome is unknown: retry with the same Idempotency-Key and body, or read it back by reference. A party lookup the provider does not answer is provider_timeout: check again before relying on it.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

Request

curl -X POST 'https://api.example.com/v1/payout-batches' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  -d '{
  "reference": "string",
  "items": [
    {
      "reference": "string",
      "amount": "120.00",
      "currency": "GHS",
      "provider": "string",
      "destination": {
        "type": "msisdn",
        "value": "string"
      },
      "note": "string"
    }
  ]
}'

const response = await fetch("https://api.example.com/v1/payout-batches", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: "{\n  \"reference\": \"string\",\n  \"items\": [\n    {\n      \"reference\": \"string\",\n      \"amount\": \"120.00\",\n      \"currency\": \"GHS\",\n      \"provider\": \"string\",\n      \"destination\": {\n        \"type\": \"msisdn\",\n        \"value\": \"string\"\n      },\n      \"note\": \"string\"\n    }\n  ]\n}"
});

import requests

response = requests.post(
    "https://api.example.com/v1/payout-batches",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Idempotency-Key": "string",
        "Content-Type": "application/json"
    },
    data="{\n  \"reference\": \"string\",\n  \"items\": [\n    {\n      \"reference\": \"string\",\n      \"amount\": \"120.00\",\n      \"currency\": \"GHS\",\n      \"provider\": \"string\",\n      \"destination\": {\n        \"type\": \"msisdn\",\n        \"value\": \"string\"\n      },\n      \"note\": \"string\"\n    }\n  ]\n}",
)

Response

{
  "batchId": "string",
  "reference": "string",
  "items": [
    {
      "reference": "string",
      "status": 0,
      "payout": {
        "reference": "string",
        "amount": "120.00",
        "currency": "GHS",
        "status": "string",
        "provider": "string",
        "fee": "120.00",
        "feeBearer": "initiator",
        "payerAmount": "120.00",
        "recipientAmount": "120.00",
        "note": "string",
        "failureReason": "string",
        "createdAt": "2019-08-24T14:15:22Z",
        "completedAt": "2019-08-24T14:15:22Z",
        "channel": "api",
        "reconciliation": {
          "status": "unchecked",
          "checkedAt": "2019-08-24T14:15:22Z"
        },
        "parent": {
          "type": "collection",
          "reference": "string"
        },
        "compensation": {
          "type": "collection",
          "reference": "string"
        }
      },
      "error": {
        "code": "string",
        "message": "string"
      }
    }
  ]
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}