Payouts API

The Payouts API lets you send money to a bank account or a mobile money destination. You can provide bank or mobile money details inline (Orchestrapay will create or reuse a recipient automatically) or pass an existing recipient_uuid.

Create a payout

Creates a new payout and initiates the transfer with the gateway. If you provide inline bank or mobile money details instead of a recipient_uuid, a recipient is created or reused transparently. The same one-of rules apply as for POST /payout-recipients: a full bank set or a full mobile money pair, not both, and no partials.

Parameters

amountinteger

The amount to send in cents. E.g. NGN 2,500 → 250000.

currencystring

A 3-letter ISO currency code (e.g. NGN).

recipient_uuidoptional, string

UUID of an existing payout recipient. Required if you do not pass a full bank set or a full mobile money set inline.

bank_account_numberoptional, string

Bank account number. Required (with the other two bank fields) for inline bank payouts when you omit recipient_uuid and do not use mobile money.

bank_account_nameoptional, string

Name on the bank account. Required with the other bank fields for inline bank payouts when not using `recipient_uuid` and not using mobile money.

bank_codeoptional, string

Bank code (e.g. "057" for Zenith Bank Nigeria). Required with the other bank fields for inline bank payouts when not using `recipient_uuid` and not using mobile money.

bank_nameoptional, string

Human-readable bank name. Optional when providing inline bank details.

nameoptional, string

Display name for the recipient (used when creating inline).

emailoptional, string

Email of the recipient (used when creating inline).

phoneoptional, string

Phone number of the recipient (used when creating inline).

mobile_money_numberoptional, string

MSISDN or wallet number for mobile money. Required (with `mobile_money_provider`) for inline mobile payouts when you omit `recipient_uuid` and do not use a full bank set.

mobile_money_provideroptional, string

Mobile money network or provider identifier. Required with `mobile_money_number` for inline mobile payouts when you omit `recipient_uuid`.

recipient_typeoptional, string

Optional: `bank_account` or `mobile_money`. Inferred if omitted from your bank vs mobile fields.

gatewayoptional, string

Payout gateway to use. When omitted, the tenant default applies.

tenantoptional, string

Tenant name. Defaults to the tenant associated with the API key.

narrationoptional, string

Description or reason for the transfer, visible on the recipient's bank statement.

idempotency_keyoptional, string

Unique key to prevent duplicate payouts. Repeating a request with the same key returns the existing payout.

webhook_urlsoptional, array

Array of URLs that receive a POST webhook whenever the payout status changes.

webhook_secretoptional, string

Secret passed as the Orchestrapay-Webhook-Secret header on every webhook call.

metadataoptional, object

Arbitrary key-value data you want to attach to the payout for your own reference.

Status Codes

201 Created: Payout was successfully created and submitted to the gateway.
200 OK: An existing payout was returned (idempotency key match).
400 Bad Request: Missing or conflicting recipient fields (e.g. neither recipient_uuid nor a valid bank or mobile money set, partial bank fields, or both a full bank set and full mobile set), or other validation or gateway errors.
401 Unauthorized: Invalid or missing API key.

POST /payouts

curl -X POST https://api.orchestrapay.com/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "NGN",
    "gateway": "mygateway",
    "narration": "Weekly seller settlement",
    "idempotency_key": "settlement-seller-1042-week-15",
    "bank_account_number": "0123456789",
    "bank_account_name": "JOHN SELLER",
    "bank_code": "058",
    "bank_name": "Guaranty Trust Bank",
    "webhook_urls": ["https://your-domain.com/webhooks/payouts"],
    "webhook_secret": "your-webhook-secret"
  }'

Response Parameters

payout_uuidstring

UUID of the payout that was created.

recipient_uuidstring

UUID of the recipient used for this payout (created or reused).

statusstring

Current payout status sub-status (e.g. pending_created, success).

gateway_payout_idstring

The gateway's reference for this transfer, if available immediately.

resource_createdboolean

Whether the payout was newly created (true) or returned from an idempotency key match (false).

RESPONSE

{
  "payout_uuid": "4c56e5c2-7ef0-4db0-8d2e-5e980f3f3bc7",
  "recipient_uuid": "76418b40-8e2d-47c3-ab2f-84e7347d9fcc",
  "status": "pending_promise",
  "gateway_payout_id": "mock-transfer-301",
  "resource_created": true
}

Query payouts

Retrieves a paginated list of payouts matching your query criteria.

Query Parameters

limitoptional, integer, default is 50

Number of results per page (max 1000).

pageoptional, integer

Page number to fetch.

sortByoptional, string

Sort by property:ASC|DESC (e.g. "created_at:DESC"). Sortable columns: id, created_at, amount.

filteroptional, object

Filter parameters.

Filter Operators

$eqEqual to

$notNot equal to

$nullIs null

$inIn array

$gtGreater than

$gteGreater than or equal to

$ltLess than

$lteLess than or equal to

$btwBetween

$ilikeCase-insensitive like

$swStarts with

$containsContains

GET /payouts

curl https://api.orchestrapay.com/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "limit=50" \
  -d "page=1" \
  -d "sortBy=created_at:DESC" \
  -d "filter.status=$eq:success" \
  -d "filter.currency=$eq:NGN"

Payout Statuses

Payouts have three main statuses:

pending: The payout is being processed by the gateway.
success: Funds were successfully transferred.
canceled: The payout failed or was rejected.

Sub-statuses

pending_created: Payout record was just created.
pending_promise: Transfer is in-flight at the gateway.
success: Transfer completed successfully.
canceled_failure: An unexpected technical error occurred.
canceled_rejected: The gateway rejected the transfer (e.g. invalid account, insufficient balance).
canceled_timeout: The payout did not complete within the expected window.

Create a payout​

Parameters​

Status Codes​

Response Parameters​

Query payouts​

Query Parameters​

Filter Operators​

Payout Statuses​

Sub-statuses​