Get beneficiary

GET/partner/v1/beneficiaries/{beneficiaryId}

Auth Bearer tokenScope partner.read

Returns one beneficiary. It must be yours or belong to a customer under your partner account. Any status can be read, disabled included.

Use it to see when a pending beneficiary becomes active. There is no beneficiary webhook event today.

Path

beneficiaryIduuidpathrequired

The beneficiaryId from Create beneficiary or List beneficiaries.

Response

beneficiaryIduuid

customerIduuid

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

corridorIduuid

The corridor the beneficiary was saved on. null for a beneficiary saved before beneficiaries were tied to corridors.

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, as sent on Create beneficiary. 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

One of pending, active, rejected, disabled. See Statuses.

createdAtUtcdatetime

When the beneficiary was saved, in UTC.

Errors

Code	HTTP	Meaning
Request.Invalid	400	beneficiaryId is not a uuid.
Auth.Unauthorized	401	The token is missing or invalid.
Auth.Forbidden	403	The token is not a partner credential, or lacks partner.read.
partner.profile_not_active	403	Your partner account is not active. Contact support.
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.

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 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

404

{
  "value": null,
  "isSuccess": false,
  "isFailure": true,
  "error": {
    "code": "partner.beneficiary_not_found",
    "name": "The beneficiary could not be found"
  },
  "title": "Resource not found",
  "traceId": "0HN..."
}