Skip to main content
Version: 202502

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.

Status notifications are sent only for payouts: configure webhook_urls and webhook_secret on POST /payouts, not on recipient create. See Payout webhooks and Payout Webhook.

Recipients: bank vs wallet​

You must pass exactly one of the following, with no mixing:

  • Bank: all of bank_account_number, bank_account_name, and bank_code, and no mobile_money_number (do not send mobile-money fields).
  • Wallet / mobile money: mobile_money_number, and no bank account fields (bank_account_number, bank_account_name, bank_code). mobile_money_provider is optional when your gateway does not require a network label.

Partial groups (for example only two bank fields) or sending both a complete bank set and mobile_money_number are rejected.

You always send gateway (required) so the correct payout integration is used.

Create a recipient​

Registers a payout destination (bank account or mobile money) with the gateway and stores it for future use. The bank vs wallet rules above apply here — they mirror POST /payouts when you create a recipient inline.

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 for wallet recipients when you are not using a full bank set.

mobile_money_provideroptional, string

Mobile money network or provider when your gateway expects one. Omit if only the wallet number is required.

recipient_typeoptional, string

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

gatewaystring

Payout gateway identifier. Must be registered for payouts and must match payouts that reference this recipient.

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 gateway, missing or conflicting bank vs mobile money fields (e.g. partial bank fields, both a full bank set and mobile_money_number), 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
}

Get a recipient​

Returns a single payout recipient by uuid. Responses include tenant_id but do not embed a nested tenant object.

Status Codes​

  • 200 OK: Recipient found (body may be null if no row matches).
  • 400 Bad Request: Invalid UUID.
  • 401 Unauthorized: Invalid or missing API key.

Path Parameters​

uuidstring (UUID)

The recipient's public identifier (returned as `recipient_uuid` from create operations).

GET /payout-recipients/a1b2c3d4-0000-4000-8000-000000000001
curl https://api.orchestrapay.com/payout-recipients/a1b2c3d4-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer YOUR_API_KEY"

Query recipients​

Retrieves a paginated list of payout recipients. Each row includes tenant_id; a nested tenant object is not included in list responses.

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-...",
      "tenant_id": 1,
      "gateway": "mygateway",
      "recipient_type": "bank_account",
      "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"
  }
}