API · Money movement

Payouts & bulk disbursement

B2C disbursements — single payout or a batch of thousands. Each leg routes through the same provider adapters that take payments, with AML screening + 4-eyes approval above your configured threshold.

5 endpointspo_

Endpoints

POST/v1/payouts

Create a single payout.

POST/v1/payouts/bulk

Submit a bulk payout batch (CSV upload or inline array).

GET/v1/payouts

List recent payouts (filter by status, recipient).

GET/v1/payouts/{id}

Retrieve a specific payout.

GET/v1/payouts/bulk/{id}

Retrieve a batch's progress (count succeeded / failed / pending).

Single payout

Name	Type	Description
`amount` required	integer	Minor units.
`currency` required	ISO 4217	"DJF", "USD", "ETB".
`provider` required	enum	Same provider set as payment_intents.
`recipient_msisdn`	E.164	For mobile-money rails.
`recipient_account`	string	For bank rails.
`recipient_name`	string	Display name (sanctions-screened).
`description`	string	Free-form, ≤140 chars.
`metadata`	map	Free-form key/value.

Bulk disbursement

Submit thousands of payouts in one request. Each row is processed independently — failures don't block the rest of the batch. Status updates stream via webhook (one event per row) and the batch summary endpoint.

POST /v1/payouts/bulk · inlinebash

curl -X POST https://api.merashub.com/v1/payouts/bulk \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: payroll_2026_05_25" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "May 2026 salary run",
    "items": [
      { "amount": 250000, "currency": "DJF", "provider": "waafi",
        "recipient_msisdn": "+25377xxxxxx1", "recipient_name": "Alice M.",
        "description": "Salary May 2026", "metadata": { "employee_id": "E-001" } },
      { "amount": 320000, "currency": "DJF", "provider": "waafi",
        "recipient_msisdn": "+25377xxxxxx2", "recipient_name": "Bob H.",
        "description": "Salary May 2026", "metadata": { "employee_id": "E-002" } }
    ]
  }'

202 Accepted · batch queuedjson

{
  "id": "po_bulk_01HZ...",
  "item_count": 2,
  "succeeded": 0,
  "failed": 0,
  "pending": 2,
  "status": "processing",
  "created_at": "2026-05-25T10:15:30Z"
}

POST /v1/payouts/bulk · CSV uploadbash

curl -X POST https://api.merashub.com/v1/payouts/bulk \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: payroll_csv_2026_05_25" \
  -H "Content-Type: text/csv" \
  --data-binary @payroll.csv

# CSV columns:
# amount,currency,provider,recipient_msisdn,recipient_account,recipient_name,description,external_ref

AML + 4-eyes

• Every payout is sanctions-screened against recipient_name in <100ms. Hits queue for analyst review.
• Amounts above your configured approval_threshold_minor auto-route to 4-eyes admin approval. Status is requires_approval until cleared.
• Bulk batches: each row is screened independently. Approved rows settle immediately; held rows wait without blocking the rest.

ℹ

Reconciliation

Each row in a bulk batch gets its own po_ ID, its own webhook events, and its own ledger entries. Reconcile against your payroll system by passing your internal employee/recipient ID in metadata.

⚠

Float requirement

Bulk batches reserve the total upfront against your available balance. If the available is short, the batch is rejected at submission time — top up first.