How-to: Manage fiat beneficiaries

A beneficiary is a registered bank account recipient for fiat payouts, like an address book entry for stablecoin payouts. Register a beneficiary for each recipient, and wait for it to become 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. Call GET /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:

curl -X GET 'https://api-sandbox.circle.com/v1/beneficiaries/requirements?destinationCountry=MX&destinationCurrency=MXN&paymentMethod=SPEI&customerType=INDIVIDUAL' \
  --header "Authorization: Bearer $API_KEY"

{
  "data": {
    "fields": [
      {
        "name": "CLABE",
        "type": "TEXT",
        "required": true,
        "pattern": "^[0-9]{18}$",
        "validationDetails": "18 digits."
      },
      {
        "name": "BANK_NAME",
        "type": "TEXT",
        "required": false,
        "pattern": "^.{1,140}$",
        "validationDetails": "Name of the recipient's bank. Maximum 140 characters."
      },
      {
        "name": "BENEFICIARY_NAME",
        "type": "TEXT",
        "required": true,
        "pattern": "^.{1,140}$",
        "validationDetails": "Full legal name. Maximum 140 characters."
      },
      {
        "name": "BENEFICIARY_ADDRESS",
        "type": "ADDRESS",
        "required": true,
        "fields": [
          { "name": "STREET", "type": "TEXT", "required": true },
          { "name": "CITY", "type": "TEXT", "required": true },
          { "name": "STATE_PROVINCE", "type": "TEXT", "required": false },
          { "name": "POSTAL_CODE", "type": "TEXT", "required": true },
          { "name": "COUNTRY", "type": "TEXT", "required": true }
        ]
      }
    ]
  }
}

In the registration request, send the fields in two objects, split by field name:

travelRule: fields that start with BENEFICIARY_, such as BENEFICIARY_NAME and BENEFICIARY_ADDRESS. These are the recipient details the Travel Rule requires.
bankAccount: all other fields, such as CLABE, IBAN, and ACCOUNT_NUMBER.

Step 2. Register a beneficiary

You can’t update a beneficiary. To fix an error, delete it and register it again with the corrected details. Use the new beneficiary ID in your payout requests.

Send the fields from Step 1 to POST /v1/beneficiaries. This example registers an individual SPEI beneficiary in Mexico:

curl -X POST 'https://api-sandbox.circle.com/v1/beneficiaries' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customerType": "INDIVIDUAL",
    "destinationCountry": "MX",
    "destinationCurrency": "MXN",
    "paymentMethod": "SPEI",
    "bankAccount": {
      "CLABE": "012345678901234567",
      "BANK_NAME": "BBVA Mexico"
    },
    "travelRule": {
      "BENEFICIARY_NAME": "Alice Garcia",
      "BENEFICIARY_ADDRESS": {
        "STREET": "Av. Reforma 100",
        "CITY": "Ciudad de Mexico",
        "STATE_PROVINCE": "CDMX",
        "POSTAL_CODE": "06600",
        "COUNTRY": "MX"
      }
    }
  }'

The response returns 201. The status is INACTIVE while Circle screens the beneficiary:

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customerType": "INDIVIDUAL",
    "destinationCountry": "MX",
    "destinationCurrency": "MXN",
    "paymentMethod": "SPEI",
    "status": "INACTIVE"
  }
}

Save the 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 is ACTIVE. 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:

curl -X GET 'https://api-sandbox.circle.com/v1/beneficiaries/{id}' \
  --header "Authorization: Bearer $API_KEY"

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "ACTIVE",
    "customerType": "INDIVIDUAL",
    "destinationCountry": "MX",
    "destinationCurrency": "MXN",
    "paymentMethod": "SPEI"
  }
}

If status is DENIED, screening rejected the beneficiary. Delete it and register a new one.

Manage existing beneficiaries

List beneficiaries

Call GET /v1/beneficiaries to retrieve your beneficiaries. Use the status query parameter to filter the results, and pageSize, pageAfter, and pageBefore to page through them.

curl -X GET 'https://api-sandbox.circle.com/v1/beneficiaries?status=ACTIVE' \
  --header "Authorization: Bearer $API_KEY"

Delete a beneficiary

Call DELETE /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.

curl -X DELETE 'https://api-sandbox.circle.com/v1/beneficiaries/{id}' \
  --header "Authorization: Bearer $API_KEY"

A successful delete returns 204 No Content.

Recover a stale beneficiary

If a corridor’s required fields change after you register a beneficiary, its status becomes STALE 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.

Fiat payouts

Managed Payments

Stablecoin payments

How-to: Manage fiat beneficiaries

Prerequisites

Steps

Step 1. Get field requirements

Step 2. Register a beneficiary

Step 3. Wait for the beneficiary to become active

Manage existing beneficiaries

List beneficiaries

Delete a beneficiary

Recover a stale beneficiary

​Prerequisites

​Steps

​Step 1. Get field requirements

​Step 2. Register a beneficiary

​Step 3. Wait for the beneficiary to become active

​Manage existing beneficiaries

​List beneficiaries

​Delete a beneficiary

​Recover a stale beneficiary

Prerequisites

Steps

Step 1. Get field requirements

Step 2. Register a beneficiary

Step 3. Wait for the beneficiary to become active

Manage existing beneficiaries

List beneficiaries

Delete a beneficiary

Recover a stale beneficiary