Update beneficiary

PATCH/partner/v1/beneficiaries/{beneficiaryId}

Auth Bearer tokenScope partner.write

Changes a saved beneficiary in one call. Send only what you want to change; everything you leave out stays as it is. The beneficiary can be yours or one of your customers'.

The bank account itself cannot change. If the account details are wrong, disable the beneficiary and create a new one.

You change	Effect on status
details.beneficiaryAddress, details.beneficiaryCity, details.website, or documentIds	Returns to pending while the payout provider reviews the change. See Statuses.
label or isDefault	Unchanged. These are Ryno's own and are not sent to the provider.

A beneficiary that is already pending stays pending. On corridors whose payout providers keep no copy of beneficiaries, and for a beneficiary suspended by Ryno, the status does not change. A disabled beneficiary cannot be edited.

Path

beneficiaryIduuidpathrequired

The beneficiary to change. An id that does not exist, is not a uuid, or belongs to someone who is not you or one of your customers is 404 partner.beneficiary_not_found.

Headers

Idempotency-Keystringheaderrequired

A key you generate per edit, at most 255 characters. Sending the same key with the same body returns the beneficiary as it is now, 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 beneficiary's owner. Values are trimmed before the bodies are compared, so a retry that differs only in surrounding spaces is the same request.

Body

All fields are optional.

detailsobject

Values to change, keyed by the field names from Get beneficiary requirements. Every value is a string. Fields you leave out are unchanged.

• You can change beneficiaryAddress, beneficiaryCity and website. Send an empty string to clear one that is optional on the corridor; a required field cannot be cleared.
• The account details cannot change: beneficiaryType, accountName, accountNumber, bankName, swiftCode, bankCode, and any other bank field the beneficiary stores. Sending one with the value it already has is accepted and ignored. Sending a different value is 422 Beneficiary.InvalidField.
• Only the fields that change are checked against the corridor's current requirements, with the same errors as Create beneficiary.

documentIdsuuid[]

The complete new list of supporting documents. It replaces the current list, so include every document that should stay attached. Send [] to remove them all. Leave it out to keep the current documents. Sending the list the beneficiary already has changes nothing.

Each document must meet the same rules as on Create beneficiary.

labelstring

Your own name for the beneficiary, at most 100 characters. Send a blank value to clear it.

isDefaultboolean

true makes this the owner's default beneficiary for its currency, and the previous default stops being the default. false removes the default.

Response

The beneficiary as it is after the edit, in the same shape as Create beneficiary. status is pending after an address, city, website or documents change, and unchanged after a label or default change.

Field and document errors

A value that breaks a rule is 422 Beneficiary.InvalidField, and a document that cannot be attached is 422 Beneficiary.InvalidDocument. Both use the reasons listed under Create beneficiary. One more applies to an edit: a field that the account details lock.

accountNumber: cannot be changed; disable this beneficiary and create a new one

If the beneficiary is not on a payout corridor, its address, city, website and documents cannot be edited either, and the reason is cannot be changed on this beneficiary.

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.InvalidEditRequest	400	label is over 100 characters.
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 changed.
Auth.Unauthorized	401	The token is missing or invalid.
Auth.Forbidden	403	The token is not a partner credential, or lacks partner.write.
partner.profile_not_active	403	Your partner account is not active. Contact support.
BeneficiaryRequirement.CustomerInactive	403	Your account is not active.
partner.profile_not_found	404	Your partner account could not be found. Contact support.
partner.beneficiary_not_found	404	No beneficiary you can see has this id. Also returned for another partner's beneficiary, which is left unchanged.
BeneficiaryRequirement.CorridorNotFound	404	The beneficiary's corridor is no longer one you are offered.
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, or you tried to change an account detail. See Field and document errors.
Beneficiary.InvalidDocument	422	A document cannot be attached. See Field and document errors.
Beneficiary.NotEditable	422	The beneficiary is disabled. Create a new one instead.
BeneficiaryRequirement.NotAvailable	422	The corridor cannot take changes right now. Do not retry unchanged.
BeneficiaryRequirement.Unavailable	503	The change 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/1d7f3b9a-2e6c-4a85-9f10-6b3c8e2d4a71 \
  -X PATCH \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f8a1c2e-beneficiary-edit-001" \
  -H "Content-Type: application/json" \
  -d '{
    "details": {
      "beneficiaryAddress": "90 Shennan Road, Futian District",
      "website": ""
    },
    "documentIds": ["9e4c7a21-3b8f-4d6e-b1a5-7c0f2e9d8b46"],
    "label": "Acme main supplier"
  }'

This changes the address, clears the website, replaces the documents and renames the beneficiary, so the beneficiary returns to pending while the payout provider reviews the change.

Response

200

{
  "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": "90 Shennan Road, Futian District",
      "beneficiaryCity": "Shenzhen"
    },
    "documentIds": ["9e4c7a21-3b8f-4d6e-b1a5-7c0f2e9d8b46"],
    "label": "Acme main supplier",
    "isDefault": true,
    "status": "pending",
    "createdAtUtc": "2026-10-25T10:42:17Z"
  },
  "isSuccess": true,
  "isFailure": false,
  "error": { "code": "", "name": "" },
  "title": null,
  "traceId": "0HN..."
}

422

{
  "value": null,
  "isSuccess": false,
  "isFailure": true,
  "error": {
    "code": "Beneficiary.InvalidField",
    "name": "accountNumber: cannot be changed; disable this beneficiary and create a new one"
  },
  "title": "Request cannot be processed",
  "traceId": "0HN..."
}

422 disabled

{
  "value": null,
  "isSuccess": false,
  "isFailure": true,
  "error": {
    "code": "Beneficiary.NotEditable",
    "name": "A disabled beneficiary cannot be edited"
  },
  "title": "Request cannot be processed",
  "traceId": "0HN..."
}

409

{
  "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..."
}