Disable beneficiary

POST/partner/v1/beneficiaries/{beneficiaryId}/disable

Auth Bearer tokenScope partner.write

Disables a beneficiary so no payout can use it. If it was the owner's default for its currency, it stops being the default. The beneficiary is kept and can still be read.

Disabling is permanent: the API has no way to enable a beneficiary again. To pay the same account later, create a new beneficiary.

Calling it again on a beneficiary that is already disabled changes nothing and returns it with 200, so a retry is safe. No Idempotency-Key is needed.

Path

beneficiaryIduuidpathrequired

The beneficiaryId from Create beneficiary or List beneficiaries.

Body

None.

Response

The beneficiary, with status set to disabled and isDefault set to false. The fields are the same as on Get beneficiary.

Errors

Code	HTTP	Meaning
Request.Invalid	400	beneficiaryId is not a uuid.
partner.customer_read_only	400	The customer is suspended or closed. Its beneficiaries can still be listed and read, but not disabled.
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.
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.

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

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