Beneficiaries
A beneficiary is a bank account a payout is sent to. You save it once, and its details are reused every time it is paid.
Every beneficiary belongs to one payout corridor: a source currency paid out as a destination currency in a destination country, for example USDT paid out as USD in China. What a beneficiary must contain depends on the corridor. A China beneficiary needs a bank from a fixed list and its SWIFT code; another country may need an IBAN or a routing number instead. Ryno tells you exactly which fields a corridor needs, so you never hard-code them.
You can save beneficiaries for two kinds of owner with the same endpoints:
- Yourself, the partner. Leave
customerIdout. - Your customers, the business and individual customers you onboarded. Send their
customerId.
Your customers are offered your corridors, so a corridor id from List payout corridors works for them too.
Endpoints
| Endpoint | Scope | |
|---|---|---|
| GET | /partner/v1/beneficiary-requirements | partner.read |
| POST | /partner/v1/beneficiaries | partner.write |
| PATCH | /partner/v1/beneficiaries/{beneficiaryId} | partner.write |
| GET | /partner/v1/beneficiaries | partner.read |
| GET | /partner/v1/beneficiaries/{beneficiaryId} | partner.read |
| POST | /partner/v1/beneficiaries/{beneficiaryId}/disable | partner.write |
Typical flow
Pick a corridor
Call List payout corridors and take the corridorId of the destination you want to pay.
Read what the corridor needs
Call Get beneficiary requirements with that corridorId. Build your form, or map your stored data, from the fields it returns. Fields with choices only accept one of the listed values.
Upload documents, if you have any
Documents are optional. To attach one, request an upload link with purpose set to beneficiary and documentCategory set to Invoice or Contract on Request document upload link, upload the file, and keep the documentId.
Create the beneficiary
Call Create beneficiary with the corridorId, the details and any documentIds. Add customerId when the beneficiary is for one of your customers.
Track its status
The beneficiary starts as pending. Read it with Get beneficiary to see when it becomes active.
Statuses
status | Meaning |
|---|---|
pending | Saved. Ryno has not finished setting it up for payouts yet. It stays pending until the payout provider approves it, which can take some time. Editing the address, city, website or documents with Update beneficiary returns an active beneficiary to pending while the provider reviews the change. |
active | Ready to be paid. |
rejected | Ryno cannot pay this account. If the address, city, website or documents were wrong, correct them with Update beneficiary, which returns it to pending. If the account details were wrong, create a new beneficiary. |
disabled | You disabled it with Disable beneficiary. It cannot be paid. The API has no way to enable it again; create a new beneficiary instead. |
There is no beneficiary webhook event today, so read the beneficiary when you need its status.
Ownership
You see your own beneficiaries and those of customers under your partner account. Nothing else.
A beneficiaryId that belongs to another partner returns 404 partner.beneficiary_not_found, exactly as an id that does not exist. The same applies to a customerId that is not yours: 404 partner.sub_customer_not_found. You cannot tell the two cases apart, by design.
Read-only customers
A customer that is suspended or closed is read only. You can still list and read its beneficiaries, but creating, updating or disabling one returns 400 partner.customer_read_only. Your own beneficiaries are never affected.
Shared response and error formats are on the API introduction.