ACTIVE before you send a payout to it.
Prerequisites
Before you begin, ensure that you’ve:- Enabled fiat payout permissions on your Managed Payments account.
- Created an API key with Managed Payments access from the Circle hub.
Steps
Step 1. Get field requirements
The required fields vary by corridor. CallGET /v1/beneficiaries/requirements
with the corridor parameters and the customerType to get the fields you must
supply.
This example gets the requirements for an individual recipient in Mexico who is
paid over SPEI, Mexico’s interbank payment system:
travelRule: fields that start withBENEFICIARY_, such asBENEFICIARY_NAMEandBENEFICIARY_ADDRESS. These are the recipient details the Travel Rule requires.bankAccount: all other fields, such asCLABE,IBAN, andACCOUNT_NUMBER.
Step 2. Register a beneficiary
Send the fields from Step 1 toPOST /v1/beneficiaries.
This example registers an individual SPEI beneficiary in Mexico:
For Mexico (
MX) beneficiaries, the last digit of the CLABE is a check digit
calculated from the first 17 digits. If it doesn’t match, the request fails with
error 400208. When you test, use a CLABE with a valid check digit, such as
012345678901234568.201. The status is INACTIVE while Circle screens the
beneficiary:
id. You use it as the destination.id when you send a payout.
Step 3. Wait for the beneficiary to become active
Circle screens the beneficiary in the background, and you can’t send a payout to it until its status isACTIVE. Subscribe to the
payouts.beneficiary.updated
webhook event to learn when screening finishes. To set up your endpoint, see
Set up a webhook endpoint.
To secure it, see Webhook security.
If you can’t receive webhooks, such as when testing without a public endpoint,
poll
GET /v1/beneficiaries/{id}
until status changes from INACTIVE:
status is DENIED, screening rejected the beneficiary. Delete it and
register a new one.
Manage existing beneficiaries
List beneficiaries
CallGET /v1/beneficiaries
to retrieve your beneficiaries. Use the status query parameter to filter the
results, and pageSize, pageAfter, and pageBefore to page through them.
Delete a beneficiary
CallDELETE /v1/beneficiaries/{id}
to delete a beneficiary. Circle permanently removes the recipient’s personal
data, and GET /v1/beneficiaries/{id} returns 404 afterward. Deleting a
beneficiary that’s already deleted also succeeds.
204 No Content.
Recover a stale beneficiary
If a corridor’s required fields change after you register a beneficiary, its status becomesSTALE and it can’t receive payouts. To recover, call
GET /v1/beneficiaries/requirements for the current fields, delete the
beneficiary, and register it again.
To send a fiat payout using an ACTIVE beneficiary, see
Send fiat payouts.