List beneficiaries

GET/partner/v1/beneficiaries

Auth Bearer tokenScope partner.read

Lists your own beneficiaries and those of every customer under your partner account, newest first. Every status is listed, disabled included; filter on status if you only want the ones that can be paid.

Query

customerIduuidquery

Return only this customer's beneficiaries. Use a customer you onboarded, or your partner ID for your own beneficiaries. Omit it to list every beneficiary you can see.

A customer that does not exist or is not under your partner account is 404 partner.sub_customer_not_found.

pageintegerquerydefault: 1

Values below 1 are treated as 1.

pageSizeintegerquerydefault: 20

Clamped to 1 to 100.

Response

itemsobject[]

One entry per beneficiary, with the same fields as Get beneficiary: beneficiaryId, customerId, corridorId, currencyCode, countryCode, rail, details, documentIds, label, isDefault, status and createdAtUtc.

pageinteger

The page returned, after clamping.

pageSizeinteger

The page size used, after clamping.

totalCountinteger

How many beneficiaries match, across all pages.

Errors

Code	HTTP	Meaning
Request.Invalid	400	customerId is not a uuid, or page or pageSize is not a whole number.
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.sub_customer_not_found	404	customerId is not a customer under your partner account.

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?customerId=5b2e8f14-7c3a-4d91-a6e0-2f9d1c7b4a83&pageSize=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

{
  "value": {
    "items": [
      {
        "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": [],
        "label": "Acme supplier",
        "isDefault": true,
        "status": "pending",
        "createdAtUtc": "2026-10-25T10:42:17Z"
      }
    ],
    "page": 1,
    "pageSize": 50,
    "totalCount": 1
  },
  "isSuccess": true,
  "isFailure": false,
  "error": { "code": "", "name": "" },
  "title": null,
  "traceId": "0HN..."
}