Skip to main content

Payout Recipients API

A payout recipient represents a bank account or mobile money destination that can receive payouts. Recipients are tenant and gateway-specific.

You typically don't need to manage recipients directly — POST /payouts handles recipient creation transparently. Use this API when you want to pre-register recipients and reuse them across multiple payouts.

Create a recipient​

Registers a payout destination (bank account or mobile money) with the gateway and stores it for future use.

You must provide exactly one of: a full bank set (bank_account_number, bank_account_name, and bank_code — no mobile_* fields), or a full mobile money set (mobile_money_number and mobile_money_provider — no bank account fields). Do not send both a complete bank set and complete mobile set, or partial bank/mobile fields.

Parameters​

bank_account_numberoptional, string

Bank account number. Required (with `bank_account_name` and `bank_code`) for bank recipients when mobile money is not used.

bank_account_nameoptional, string

Name on the bank account, as it appears at the bank. Required with the other bank fields for bank recipients.

bank_codeoptional, string

Bank code (e.g. "057" for Zenith Bank Nigeria, "058" for GTBank). Required with the other bank fields for bank recipients.

bank_nameoptional, string

Human-readable bank name for display purposes.

nameoptional, string

Display name for the recipient (person or business name).

emailoptional, string

Email address of the recipient.

phoneoptional, string

Phone number of the recipient.

mobile_money_numberoptional, string

MSISDN or wallet number for mobile money. Required (with `mobile_money_provider`) when not using a full bank set.

mobile_money_provideroptional, string

Mobile money network or provider identifier (e.g. as defined for your gateway). Required with `mobile_money_number` for mobile money recipients.

recipient_typeoptional, string

Discriminator: `bank_account` (default) or `mobile_money`. Inferred from your bank vs mobile fields if omitted.

gatewayoptional, string

Payout gateway to register with. When omitted, the tenant default applies.

idempotency_keyoptional, string

Unique key to prevent duplicate recipient creation. Repeating a request with the same key returns the existing recipient.

metadataoptional, object

Arbitrary key-value data to attach to this recipient.

Status Codes​

  • 201 Created: Recipient was registered successfully.
  • 200 OK: An existing recipient was returned (idempotency key match).
  • 400 Bad Request: Missing or conflicting bank vs mobile money fields (e.g. partial bank fields, both a full bank set and mobile money set, or mobile money fields without both mobile_money_number and mobile_money_provider), unsupported gateway, or gateway registration failed.
  • 401 Unauthorized: Invalid or missing API key.
POST /payout-recipients
curl -X POST https://api.orchestrapay.com/payout-recipients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_account_number": "0123456789",
    "bank_account_name": "JOHN SELLER",
    "gateway": "mygateway",
    "bank_code": "058",
    "bank_name": "Guaranty Trust Bank",
    "name": "John Seller",
    "email": "john.seller@example.com",
    "idempotency_key": "recipient-john-seller-gtb-0123456789"
  }'

Response Parameters​

recipient_uuidstring

UUID of the recipient that was created or matched.

gateway_recipient_idstring

The gateway's own identifier for this recipient (e.g. a recipient code returned by the gateway).

resource_createdboolean

Whether a new recipient was created (true) or an existing one returned via idempotency key (false).

RESPONSE
{
  "recipient_uuid": "76418b40-8e2d-47c3-ab2f-84e7347d9fcc",
  "gateway_recipient_id": "mock-recipient-88",
  "resource_created": true
}

Query recipients​

Retrieves a paginated list of payout recipients.

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.

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 /payout-recipients
curl https://api.orchestrapay.com/payout-recipients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "limit=50" \
  -d "page=1" \
  -d "filter.gateway=$eq:mygateway"

Response Parameters​

data[]array

Array of recipient objects.

metaobject

Pagination metadata (itemsPerPage, totalItems, currentPage, totalPages, sortBy).

linksobject

Pagination links (first, previous, current, next, last).

RESPONSE
{
  "data": [
    {
      "id": 88,
      "uuid": "a1b2c3d4-...",
      "gateway": "mygateway",
      "gateway_recipient_id": "mock-recipient-88",
      "bank_account_number": "0123456789",
      "bank_account_name": "JOHN SELLER",
      "bank_code": "058",
      "bank_name": "Guaranty Trust Bank",
      "name": "John Seller",
      "created_at": "2026-04-05T13:00:00Z",
      "updated_at": "2026-04-05T13:00:00Z"
    }
  ],
  "meta": {
    "itemsPerPage": 50,
    "totalItems": 1,
    "currentPage": 1,
    "totalPages": 1,
    "sortBy": [["created_at", "DESC"]]
  },
  "links": {
    "first": "https://api.orchestrapay.com/payout-recipients?page=1&limit=50",
    "previous": null,
    "current": "https://api.orchestrapay.com/payout-recipients?page=1&limit=50",
    "next": null,
    "last": "https://api.orchestrapay.com/payout-recipients?page=1&limit=50"
  }
}