Create Beneficiary

Save a payout recipient. Scheme and routing keys must match a corridor from GET /corridors. Emits event.beneficiary.created.

POST /beneficiaries

Create Beneficiary

cURL

curl --request POST \
  --url https://20b9-41-90-209-232.ngrok-free.app/v1/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "kind": "person",
  "currency": "NGN",
  "scheme": "ng_nip",
  "holder_name": "Ada Okoye",
  "routing": {
    "bank_code": "058",
    "account_number": "0123456789"
  }
}
'

200

{
  "object": "beneficiary",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "person",
  "name": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "business_name": "<string>",
  "nickname": "<string>",
  "email": "<string>",
  "relationship": "<string>",
  "address": {
    "line_1": "<string>",
    "line_2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "currency": "<string>",
  "country": "<string>",
  "method": "<string>",
  "scheme": "<string>",
  "scheme_label": "<string>",
  "settlement": "<string>",
  "holder_name": "<string>",
  "routing": {},
  "route_label": "<string>",
  "status": "<string>",
  "missing_fields": [
    "<string>"
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "archived_at": "2023-11-07T05:31:56Z",
  "livemode": true,
  "environment": "live"
}

Authorizations

Authorization · string · header · required

Secret API key from Settings → Developers → API keys. Example: Authorization: Bearer sk_test_…

Body

application/json

kind · enum<string> · required

Recipient type. Use person with first/last name, or business with business_name.

Available options: person, business

Example:

"person"

currency · string · required

Payout currency the recipient receives (must match the scheme).

Example:

"NGN"

scheme · string · required

Corridor scheme id from GET /corridors (e.g. ng_nip, ke_mpesa, eu_sepa, us_ach). Determines required routing keys.

Example:

"ng_nip"

holder_name · string · required

Account holder name as registered with the receiving bank or wallet.

Example:

"Ada Okoye"

routing · object · required

Scheme-specific account identifiers. Keys depend on the corridor (e.g. bank_code + account_number for ng_nip). See corridor field definitions from GET /corridors.

Example:

{
  "bank_code": "058",
  "account_number": "0123456789"
}

first_name · string

Given name (required when kind is person).

Example:

"Ada"

last_name · string

Family name (required when kind is person).

Example:

"Okoye"

business_name · string

Legal business name (required when kind is business).

nickname · string

Optional label shown in your dashboard and lists.

email · string<email>

Optional contact email for the recipient.

relationship · string

Relationship code from GET /corridors → relationships (e.g. supplier, employee). Required for some personal corridors.

address · object

Postal address for the recipient when the corridor requires it.

Show child attributes

country · string

ISO 3166-1 alpha-2 country for the corridor (e.g. NG).

Example:

"NG"

Response

200

application/json

Created beneficiary

object · enum<string>

Object type discriminator.

Available options: beneficiary

id · string<uuid>

Beneficiary id — pass as beneficiary_id on payouts.

kind · enum<string>

Recipient type.

Available options: person, business

name · string

Display name derived from person or business fields.

first_name · string

Given name when kind is person.

last_name · string

Family name when kind is person.

business_name · string

Legal name when kind is business.

nickname · string

Optional display label.

email · string

Contact email.

relationship · string

Relationship to your workspace.

address · object

Postal address for the recipient when the corridor requires it.

Show child attributes

currency · string

Currency the recipient is paid in.

country · string

Corridor country.

method · string

High-level rail family (bank, mobile_money, …).

scheme · string

Corridor scheme id.

scheme_label · string

Human-readable scheme name.

settlement · string

Typical settlement timing (e.g. Instant, Same day).

holder_name · string

Account holder name on the rail.

routing · object

Scheme-specific account identifiers (may be partially masked).

route_label · string

Short label for the destination account.

status · string

Lifecycle status (active, archived, …).

missing_fields · string[]

Fields still required before the beneficiary can be paid.

created_at · string<date-time>

When the beneficiary was created (UTC).

updated_at · string<date-time>

When the beneficiary was last updated (UTC).

archived_at · string<date-time>

When archived, if applicable.

livemode · boolean

true when created with a live key.

environment · enum<string>

Environment of the creating API key.

Available options: live, sandbox