Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.circle.com/llms.txt

Use this file to discover all available pages before exploring further.

Redeem (offramp) USDC or EURC in your Circle Mint balance to fiat and send funds to a linked bank account. You can track payout status from pending through complete or failed, and handle returned withdrawals caused by bank-side rejections. Payouts route through the /wires endpoint and support standard wires, real-time interbank rails (RTP, SPEI, SEPA, CHATS) where available, and book transfers when applicable — Circle selects the rail based on your destination bank and region.

​
Prerequisites

Before you begin:
  • Complete the account and API key setup.
  • Have a funded Circle Mint account with available USDC or EURC balance.
  • Have a linked bank account. If you have not linked one, see Deposit Fiat Step 1.
  • If your Circle Mint account is domiciled in Singapore or France, verify your payout recipients through the Mint Console before proceeding. Unverified recipients cause payouts to remain in pending status.

​
Step 1. Verify your balance

Before you initiate a withdrawal, confirm that your available balance covers the amount you plan to send. 
curl -X GET https://api-sandbox.circle.com/v1/businessAccount/balances \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json"
Expected response: 
{
  "data": {
    "available": [
      {
        "amount": "150.00",
        "currency": "USD"
      }
    ],
    "unsettled": [
      {
        "amount": "25.00",
        "currency": "USD"
      }
    ]
  }
}
The available array shows funds you can withdraw immediately. The unsettled array shows funds that are still being processed and are not yet available.

​
Step 2. Create a payout

Use the create a payout endpoint to send funds from your Circle Mint account to your linked bank account. 
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/payouts \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "'$(uuidgen)'", "destination": {"type": "wire", "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636"}, "amount": {"currency": "USD", "amount": "75.00"}}'
Replace the destination.id value with the bank account ID returned when you linked your bank account. Expected response: 
{
  "data": {
    "id": "9cf38c76-cac4-40d8-a516-f46e9a610a85",
    "amount": {
      "amount": "75.00",
      "currency": "USD"
    },
    "status": "pending",
    "sourceWalletId": "1016875042",
    "destination": {
      "type": "wire",
      "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
      "name": "WELLS FARGO BANK, NA ****0010"
    },
    "createDate": "2024-01-15T14:22:31.062Z",
    "updateDate": "2024-01-15T14:22:31.062Z"
  }
}
Record the id from the response to check the payout status in the next step.

​
Step 3. Check the payout status

Use the get a payout endpoint to check the current status of your withdrawal. 
curl -X GET https://api-sandbox.circle.com/v1/businessAccount/payouts/9cf38c76-cac4-40d8-a516-f46e9a610a85 \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json"
A payout moves through the following statuses:
  • pending: Circle has received the payout request and is processing it.
  • complete: Funds have been sent to the receiving bank.
  • failed: The payout could not be processed. Check the errorCode field for details.
Expected response for a completed payout: 
{
  "data": {
    "id": "9cf38c76-cac4-40d8-a516-f46e9a610a85",
    "amount": {
      "amount": "75.00",
      "currency": "USD"
    },
    "status": "complete",
    "sourceWalletId": "1016875042",
    "destination": {
      "type": "wire",
      "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
      "name": "WELLS FARGO BANK, NA ****0010"
    },
    "createDate": "2024-01-15T14:22:31.062Z",
    "updateDate": "2024-01-16T09:15:42.778Z"
  }
}
Payouts are asynchronous. To track status changes without polling, subscribe to payouts webhook notifications. Alternatively, poll the get a payout endpoint at a reasonable interval until the status reaches complete or failed.

​
Returned withdrawals

Even after a payout reaches complete status, bank-side issues can cause the wire to be returned. Common reasons include:
  • Incorrect account details, such as a wrong routing number or a closed account.
  • Compliance holds at the receiving bank.
  • Beneficiary name mismatch between the payout and the bank account on file.
When a wire is returned, the funds are re-credited to your Circle Mint balance. Monitor webhook notifications for payouts events to detect returns. If a payout fails or is returned, verify the bank account details and retry with a new idempotency key.

​
See also