Quickstart: Send fiat payouts

Send local currency to a recipient’s bank account, funded by the USDC in your Managed Payments account. Circle acts as the Originating Financial Institution (OFI) on the Circle Payments Network (CPN), which routes the payout to a Beneficiary Financial Institution (BFI) that delivers the local fiat. This quickstart pays an individual in Mexico over SPEI, Mexico’s interbank payment system. The same steps apply to every corridor.

Prerequisites

Before you begin, ensure that you’ve:

Completed Managed Payments onboarding with fiat payout permissions enabled on your account.
Funded your Managed Payments account with enough USDC to cover the payout amount and fees.
Created an API key with Managed Payments access from the Circle hub.
(Optional) Set up a webhook endpoint to receive beneficiary and payout events. See Set up a webhook endpoint.

Step 1: Discover a corridor (optional)

Call GET /v1/beneficiaries/corridors to list the corridors available on your account. Each one is a combination of destination country, currency, payment method, and customer type. If you already know which corridor you need, skip to step 2.

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

{
  "data": [
    {
      "destinationCountry": "MX",
      "destinationCurrency": "MXN",
      "paymentMethod": "SPEI",
      "customerTypes": ["INDIVIDUAL", "BUSINESS"]
    }
  ]
}

The response has one entry for each corridor. This example shows only the one the rest of this quickstart uses: MX / MXN / SPEI / INDIVIDUAL.

Step 2: Get field requirements

Each corridor needs a different set of fields to register a beneficiary. Call GET /v1/beneficiaries/requirements with the corridor parameters.

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": "BENEFICIARY_NAME",
        "type": "TEXT",
        "required": true,
        "pattern": "^.{1,140}$"
      },
      {
        "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 next step, you send these fields in two objects, split by field name:

bankAccount: fields that don’t start with BENEFICIARY_, such as CLABE.
travelRule: fields that start with BENEFICIARY_, such as BENEFICIARY_NAME and BENEFICIARY_ADDRESS.

Step 3: Register a beneficiary

Send the collected fields to POST /v1/beneficiaries. Use a stable idempotencyKey so retries don’t create duplicate records.

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"
    },
    "travelRule": {
      "BENEFICIARY_NAME": "Alice Garcia",
      "BENEFICIARY_ADDRESS": {
        "STREET": "Av. Reforma 100",
        "CITY": "Ciudad de Mexico",
        "STATE_PROVINCE": "CDMX",
        "POSTAL_CODE": "06600",
        "COUNTRY": "MX"
      }
    }
  }'

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

Save the beneficiary id. You use it as the destination.id in step 6. To list, delete, or recover beneficiaries, see Manage fiat beneficiaries.

Step 4: Wait for the beneficiary to become active

The beneficiary starts as INACTIVE while Circle screens it, and you can’t send a payout until it’s ACTIVE. Use a webhook to get notified when screening finishes, or poll if you can’t receive webhooks, such as when testing without a public endpoint.

Webhook
Polling

Subscribe to the payouts.beneficiary.updated webhook event. When screening finishes, you receive a notification with status set to ACTIVE or DENIED:

{
  "subscriptionId": "00000000-0000-4000-8000-000000000002",
  "notificationId": "11111111-1111-4111-8111-111111111131",
  "notificationType": "payouts.beneficiary.updated",
  "notification": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customerType": "INDIVIDUAL",
    "destinationCountry": "MX",
    "destinationCurrency": "MXN",
    "paymentMethod": "SPEI",
    "status": "ACTIVE",
    "riskDecision": "ACTIVE",
    "riskScreenedDate": "2026-08-25T19:31:20.000Z",
    "fieldManifest": "[\"BENEFICIARY_ADDRESS\",\"BENEFICIARY_NAME\",\"CLABE\"]",
    "createDate": "2026-08-25T19:30:45.123Z",
    "updateDate": "2026-08-25T19:31:20.000Z"
  },
  "timestamp": "2026-08-25T19:31:21.000000000Z",
  "version": 2
}

The beneficiary is in notification. Use updateDate to keep the latest status.

Poll GET /v1/beneficiaries/{id} until status changes.

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 the status is DENIED, screening rejected the beneficiary. Delete it and register a new one.

Step 5: Get a payout quote

A quote locks the exchange rate and fees for a payout. Call POST /v1/payouts/quotes before you send the payout. This example is an exact-in quote. You set the USDC amount in from.amount, and the response shows the MXN amount your recipient receives after fees. For an exact-out quote, set to.amount in MXN instead, and the response shows the USDC amount debited. The useCase field describes who is sending and who is receiving. B2C is a business sending to an individual. The other values are B2B, C2B, and C2C.

curl -X POST "https://api-sandbox.circle.com/v1/payouts/quotes" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "useCase": "B2C",
    "from": {
      "currency": "USDC",
      "amount": "100.00"
    },
    "to": {
      "currency": "MXN",
      "country": "MX",
      "rail": "SPEI"
    }
  }'

{
  "data": [
    {
      "id": "q1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "from": {
        "currency": "USDC",
        "amount": "100.00"
      },
      "to": {
        "currency": "MXN",
        "amount": "1975.50",
        "country": "MX",
        "rail": "SPEI"
      },
      "fees": [
        {
          "type": "FIAT_PAYOUT_FEE",
          "amount": "1.50",
          "currency": "USDC"
        }
      ],
      "expiresAt": "2026-09-10T16:05:00.000Z"
    }
  ]
}

Quotes expire at expiresAt. If a quote expires, request a new one.

Save the quote id. You use it as the quoteId in step 6.

Step 6: Send the payout

Create the payout with POST /v1/payouts. Set destination.type to fiat_address_book, destination.id to the beneficiary id from step 3, and quoteId to the quote id from step 5. Set amount to the quote’s from.amount, reasonForPayment to a code from the payment reason codes, and customerRefId to your own reference for the payout.

curl -X POST "https://api-sandbox.circle.com/v1/payouts" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "idempotencyKey": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "destination": {
      "type": "fiat_address_book",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "amount": {
      "amount": "100.00",
      "currency": "USDC"
    },
    "quoteId": "q1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "useCase": "B2C",
    "reasonForPayment": "PMT001",
    "customerRefId": "order-9876"
  }'

{
  "data": {
    "id": "p9b8c7d6-e5f4-3210-abcd-ef1234567890",
    "status": "pending",
    "amount": {
      "amount": "100.00",
      "currency": "USDC"
    }
  }
}

The payout starts as pending.

Step 7: Confirm the payout completed

Track the payout with the mint.payout webhook event or by polling GET /v1/payouts/{id}. While the payout is in progress, Circle sends mint.payout events with status still pending. The final event has a status of complete or failed. This example is the final event for a completed payout. When status is complete, toAmount shows the fiat amount sent to the recipient.

{
  "subscriptionId": "00000000-0000-4000-8000-000000000002",
  "notificationId": "11111111-1111-4111-8111-111111111111",
  "notificationType": "mint.payout",
  "notification": {
    "id": "p9b8c7d6-e5f4-3210-abcd-ef1234567890",
    "status": "complete",
    "destination": {
      "type": "fiat_address_book",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "amount": {
      "amount": "100.00",
      "currency": "USDC"
    },
    "toAmount": {
      "amount": "1975.50",
      "currency": "MXN"
    },
    "createDate": "2026-09-10T16:01:00.000Z",
    "updateDate": "2026-09-10T16:02:30.000Z"
  },
  "timestamp": "2026-09-10T16:02:30.500000000Z",
  "version": 2
}

Fiat payouts

Managed Payments

Stablecoin payments

Quickstart: Send fiat payouts

Prerequisites

Step 1: Discover a corridor (optional)

Step 2: Get field requirements

Step 3: Register a beneficiary

Step 4: Wait for the beneficiary to become active

Step 5: Get a payout quote

Step 6: Send the payout

Step 7: Confirm the payout completed

​Prerequisites

​Step 1: Discover a corridor (optional)

​Step 2: Get field requirements

​Step 3: Register a beneficiary

​Step 4: Wait for the beneficiary to become active

​Step 5: Get a payout quote

​Step 6: Send the payout

​Step 7: Confirm the payout completed

Prerequisites

Step 1: Discover a corridor (optional)

Step 2: Get field requirements

Step 3: Register a beneficiary

Step 4: Wait for the beneficiary to become active

Step 5: Get a payout quote

Step 6: Send the payout

Step 7: Confirm the payout completed