Create beneficiary

POST/partner/v1/beneficiaries

Auth Bearer tokenScope partner.write

Saves a bank account to pay out to, on one payout corridor, in one call. The beneficiary is yours when you leave customerId out, or one of your customers' when you send it.

Read the corridor's fields first with Get beneficiary requirements, then send a value for each field under the same name in details. Ryno checks every value against those rules and answers the first one that fails, naming the field, so you can show the error next to it.

A new beneficiary starts as pending. See Statuses.

Headers

Idempotency-Keystringheaderrequired

A key you generate per beneficiary, at most 255 characters. Sending the same key with the same body returns the beneficiary the first call created, so retry a timed-out call with the key you already used. Sending the same key with a different body is 409 Beneficiary.IdempotencyConflict.

Keys are scoped to the owner: the same key used for two different customers creates two beneficiaries. Values are trimmed and empty values are left out before the bodies are compared, so a retry that differs only in surrounding spaces is the same request.

Body

corridorIduuidrequired

A corridorId from List payout corridors. It is the same for you and your customers.

customerIduuid

The customer the beneficiary is for: a business or individual customer you onboarded. Leave it out for your own beneficiary; your own partner ID works too. A customer that does not exist or is not under your partner account is 404 partner.sub_customer_not_found.

detailsobjectrequired

The beneficiary's values, keyed by the field names from Get beneficiary requirements, for example { "accountNumber": "AB12CD34" }. Every value is a string.

Send every field marked required.
For a field with choices, send one of the values exactly as listed.
For a field with filledFrom, send the matching attribute of the choice you sent. For example, the swiftCode of the chosen bankName.
A name the corridor does not list is refused, even with an empty value. This catches misspelt field names.
Values are trimmed. An empty value is the same as leaving the field out.

documentIdsuuid[]

Supporting documents to attach, at most the corridor's documents.maxCount. Optional. Each must be:

requested with purpose set to beneficiary on Request document upload link, for the same owner as this beneficiary: your partner ID for your own, or the customer's id for theirs;
uploaded, and clean after malware scanning;
of a type (the documentCategory it was requested with) and file type the corridor lists, and no larger than its maxSizeBytes.

A document that is still being scanned is refused as not found or not ready. Scanning usually takes seconds; retry with the same Idempotency-Key.

Upload links for beneficiary documents are issued for you and your business customers only, so an individual customer's beneficiary is saved without documents.

labelstring

Your own name for the beneficiary, at most 100 characters. Optional.

isDefaultbooleandefault: false

Make this the owner's default beneficiary for the corridor's currency. The owner's previous default for that currency stops being the default.

Response

The beneficiary that was created.

beneficiaryIduuid

Ryno's id for the beneficiary. Keep it; a payout will reference it.

customerIduuid

The owner: your partner ID, or the customer's id.

corridorIduuid

The corridor the beneficiary was saved on.

currencyCodestring

The currency the beneficiary receives, for example USD.

countryCodestring

The beneficiary's country, ISO 3166-1 alpha-3, for example CHN.

railstring

How the beneficiary is paid, for example RTGS.

detailsobject

The saved values, keyed by field name. Only fields with a value are included.

documentIdsuuid[]

The attached documents. Empty when there are none.

labelstring

Your name for the beneficiary, or null.

isDefaultboolean

Whether this is the owner's default beneficiary for currencyCode.

statusstring

pending for a new beneficiary. One of pending, active, rejected, disabled. See Statuses.

createdAtUtcdatetime

When the beneficiary was saved, in UTC.

Field and document errors

A value that breaks a rule is 422 Beneficiary.InvalidField. error.name starts with the field name, then the reason:

accountNumber: is not in the accepted format

Fields are checked in the order Get beneficiary requirements lists them, then any name the corridor does not list. Only the first failure is returned. The reasons are:

Reason	Fix
`is required`	Send a value.
`must not contain control characters`	Remove line breaks, tabs and other control characters.
`is not in the accepted format`	Match every one of the field's `patterns`.
`must be one of the accepted values`	Send one of the field's `choices`, exactly.
`must be N to M characters`, `must be at least N characters`, `must be at most N characters`	Respect `minLength` and `maxLength`.
`must be the <field> of the chosen <other field>`	Send the attribute of the choice you made, for example the chosen bank's `swiftCode`.
`is not a field of this corridor`	Remove the field, or fix its name.

A document that cannot be attached is 422 Beneficiary.InvalidDocument. error.name starts with its position in documentIds:

documentIds[0]: not found or not ready

Reason	Fix
`not found or not ready`	The id is unknown, belongs to another owner, or is still being scanned. Check the owner, or retry shortly.
`is listed more than once`	Send each id once.
`more than N documents`	Send at most `documents.maxCount`.
`is not a beneficiary document`	Request the upload link with `purpose` set to `beneficiary`.
`is quarantined`	The file failed malware scanning. Upload a clean file with a new link.
`has a document type this corridor does not accept`	Request the upload link with a `documentCategory` from `documents.types`.
`has a file type this corridor does not accept`	Use a file type from `documents.contentTypes`.
`is larger than N bytes`	Upload a smaller file.

Errors

Code	HTTP	Meaning
`idempotency.key_required`	400	No `Idempotency-Key` header, or it is blank.
`idempotency.key_invalid`	400	More than one `Idempotency-Key` header, or the key is longer than 255 characters.
`Beneficiary.InvalidRequest`	400	`corridorId` or `details` is missing, `label` is over 100 characters, or `customerId` is the empty uuid.
`Request.Invalid`	400	The body is not valid JSON, or a field has the wrong type.
`partner.customer_read_only`	400	The customer is suspended or closed. Its beneficiaries can still be listed and read, but not given new ones.
`Auth.Unauthorized`	401	The token is missing or invalid.
`Auth.Forbidden`	403	The token is not a partner credential, or lacks `partner.write`.
`BeneficiaryRequirement.CustomerInactive`	403	Your account is not active.
`partner.sub_customer_not_found`	404	`customerId` is not a customer under your partner account.
`BeneficiaryRequirement.CustomerNotFound`	404	Your account could not be found. Contact support.
`BeneficiaryRequirement.CorridorNotFound`	404	The corridor is not one you are offered. Use an id from List payout corridors.
`Beneficiary.IdempotencyConflict`	409	The `Idempotency-Key` was already used for this owner with a different body. Use a new key.
`Beneficiary.InvalidField`	422	A value breaks the corridor's rules. See Field and document errors.
`Beneficiary.InvalidDocument`	422	A document cannot be attached. See Field and document errors.
`BeneficiaryRequirement.NotAvailable`	422	The corridor cannot take beneficiaries yet. Do not retry unchanged.
`BeneficiaryRequirement.Unavailable`	503	Beneficiaries cannot be saved right now. Retry with backoff, using the same key.

The 401, 429 and 503 responses from the API gateway use a different body. See Errors.

Request

curl https://gateway.sandbox.rynopay.io/api/partner/v1/beneficiaries \
  -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f8a1c2e-beneficiary-001" \
  -H "Content-Type: application/json" \
  -d '{
    "corridorId": "c2f6d7a4-3b1e-4e8a-9d0c-5a7b1e2f3c44",
    "customerId": "5b2e8f14-7c3a-4d91-a6e0-2f9d1c7b4a83",
    "details": {
      "beneficiaryType": "Business",
      "accountName": "Shenzhen Acme Trading Co., Ltd.",
      "accountNumber": "6222021001123456789",
      "bankName": "Bank of China",
      "swiftCode": "BKCHCNBJXXX",
      "beneficiaryAddress": "88 Shennan Road, Futian District",
      "beneficiaryCity": "Shenzhen"
    },
    "documentIds": ["9e4c7a21-3b8f-4d6e-b1a5-7c0f2e9d8b46"],
    "label": "Acme supplier",
    "isDefault": true
  }'

Leave customerId out to save the beneficiary for yourself.

Response

{
  "value": {
    "beneficiaryId": "1d7f3b9a-2e6c-4a85-9f10-6b3c8e2d4a71",
    "customerId": "5b2e8f14-7c3a-4d91-a6e0-2f9d1c7b4a83",
    "corridorId": "c2f6d7a4-3b1e-4e8a-9d0c-5a7b1e2f3c44",
    "currencyCode": "USD",
    "countryCode": "CHN",
    "rail": "RTGS",
    "details": {
      "beneficiaryType": "Business",
      "accountName": "Shenzhen Acme Trading Co., Ltd.",
      "accountNumber": "6222021001123456789",
      "bankName": "Bank of China",
      "swiftCode": "BKCHCNBJXXX",
      "beneficiaryAddress": "88 Shennan Road, Futian District",
      "beneficiaryCity": "Shenzhen"
    },
    "documentIds": ["9e4c7a21-3b8f-4d6e-b1a5-7c0f2e9d8b46"],
    "label": "Acme supplier",
    "isDefault": true,
    "status": "pending",
    "createdAtUtc": "2026-10-25T10:42:17Z"
  },
  "isSuccess": true,
  "isFailure": false,
  "error": { "code": "", "name": "" },
  "title": null,
  "traceId": "0HN..."
}

{
  "value": null,
  "isSuccess": false,
  "isFailure": true,
  "error": {
    "code": "Beneficiary.InvalidField",
    "name": "swiftCode: must be the swiftCode of the chosen bankName"
  },
  "title": "Request cannot be processed",
  "traceId": "0HN..."
}

{
  "value": null,
  "isSuccess": false,
  "isFailure": true,
  "error": {
    "code": "Beneficiary.IdempotencyConflict",
    "name": "The idempotency key was already used for a different beneficiary request"
  },
  "title": "Conflict",
  "traceId": "0HN..."
}

Headers​

Body​

Response​

Field and document errors​

Errors​

Headers

Body

Response

Field and document errors

Errors