Create a payout

Fund and queue a batch disbursement to many external bank accounts.

POST/v1/payouts
Idempotentpayout

Creates a batch and accepts it for disbursement. The funds (items + fees) are debited from the source wallet up front; the batch returns 202 Accepted with status: "processing" and every item pending. Items then resolve one by one - the batch settles to completed, partially_completed, or failed depending on how many items land. Requires an Idempotency-Key.

Try it, for realPOST /payoutsscope: payout

Test keys only. Never paste a live key. Your key is stored only in this browser (localStorage) and sent only to the same-origin playground proxy.

›Equivalent request (curl / TypeScript)
curl
curl -X POST https://sandbox.api.acute.network/v1/payouts \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: …" \
  -d '{"sourceWalletId":"acuinf483920175566wlt","items":[{"amount":500000,"accountNumber":"0123456789","bankCode":"044","accountName":"ADA LOVELACE"},{"amount":250000,"accountNumber":"1098765432","bankCode":"058"}]}'
TypeScript
const res = await fetch("https://sandbox.api.acute.network/v1/payouts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACUTE_TEST_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({"sourceWalletId":"acuinf483920175566wlt","items":[{"amount":500000,"accountNumber":"0123456789","bankCode":"044","accountName":"ADA LOVELACE"},{"amount":250000,"accountNumber":"1098765432","bankCode":"058"}]}),
});
const { data, meta } = await res.json();

# disburse to three accounts
curl -X POST https://sandbox.api.acute.network/v1/payouts \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7e1a9c40-3b2d-4f5e-8a6b-1c2d3e4f5a6b" \
  -d '{
    "sourceWalletId": "acuinf483920175566wlt",
    "items": [
      { "amount": 500000, "accountNumber": "0123456789", "bankCode": "044", "accountName": "ADA LOVELACE" },
      { "amount": 250000, "accountNumber": "1098765432", "bankCode": "058" },
      { "amount": 750000, "accountNumber": "2233445566", "bankCode": "033" }
    ]
  }'
{
  "success": true,
  "statusCode": 202,
  "data": {
    "id": "acuinf771045620398pyo",
    "sourceWalletId": "acuinf483920175566wlt",
    "totalAmount": 1500000,
    "totalFee": 36000,
    "itemCount": 3,
    "status": "processing",
    "items": [
      {
        "id": "acuinf610248379915poi",
        "amount": 500000,
        "fee": 12000,
        "status": "pending",
        "counterparty": { "accountNumber": "0123456789", "accountName": "ADA LOVELACE", "bankCode": "044" },
        "failureReason": null
      },
      {
        "id": "acuinf338817240056poi",
        "amount": 250000,
        "fee": 12000,
        "status": "pending",
        "counterparty": { "accountNumber": "1098765432", "accountName": null, "bankCode": "058" },
        "failureReason": null
      },
      {
        "id": "acuinf905513620847poi",
        "amount": 750000,
        "fee": 12000,
        "status": "pending",
        "counterparty": { "accountNumber": "2233445566", "accountName": null, "bankCode": "033" },
        "failureReason": null
      }
    ],
    "currency": "NGN",
    "createdAt": "2026-06-24T10:40:09.224Z"
  },
  "meta": { "requestId": "req_4f9c2a7e1b0d8c3a5e6f10a2" }
}

202 means accepted, not paid

The 202 only confirms the batch was funded and queued - no item has paid yet. Items resolve out of band: poll get a payout or react to the payout.completed / payout.partially_completed webhooks. A batch where some items bounce settles partially_completed, and each failed item carries its own failureReason. The payouts guide walks partial completion.

sourceWalletIdstringbodyrequired

The wallet to fund the batch from (acuinf…wlt). Must hold enough for every item plus the per-item fees - otherwise 422 (WALLET_INSUFFICIENT_FUNDS).

itemsPayoutItem[]bodyrequired

The disbursements, between 1 and 500 per batch. Each item is { amount, accountNumber, bankCode, accountName? }.

items[].amountinteger (kobo)bodyrequired

Amount to send to this account, in kobo. Positive integer. Fees are added on top and debited from the source.

items[].accountNumberstringbodyrequired

Destination NUBAN - exactly 10 digits.

items[].bankCodestringbodyrequired

Destination bank code. See the banks reference.

items[].accountNamestringbodyoptional

Account holder name. Optional - Acute resolves it when omitted.

idstringrequired

The payout reference (acuinf…pyo). Store this - it's how you address the batch.

sourceWalletIdstringrequired

The funding wallet reference.

totalAmountnumber (kobo)required

The sum of every item's amount (fees excluded).

totalFeenumber (kobo)required

The sum of every item's fee. totalAmount + totalFee is what's debited from the source wallet.

itemCountintegerrequired

How many items are in the batch.

status'processing' | 'completed' | 'partially_completed' | 'failed'required

Starts processing. Resolves to completed (all items paid), partially_completed (some paid, some failed), or failed (none paid).

itemsPayoutItemData[]required

The per-item breakdown. Each item is { id, amount, fee, status, counterparty, failureReason }, where status is pending | processing | completed | failed and counterparty is { accountNumber, accountName, bankCode }. failureReason is populated when that item's status is failed.

currencystringrequired

The currency (NGN).

createdAtstringrequired

ISO-8601 creation timestamp.