Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and stablecoin payments, embed digital wallets into your product or service, or power your internet marketplace.

✨ Wire Payouts Quickstart

Get started with Circle Payments API and send your first wire payout in just a few minutes!

The Circle Payments API allows you to send payouts from stablecoin balances you control to your end users' bank accounts in 80+ countries.

1. Get an API key

The Circle Payments API uses API keys as the mechanism to authenticate client requests. The API key must be set in the Authorization header of the request sent from your backend server. The format of the header is Bearer secret-key-value.

Learn more about authenticating API calls here.

To obtain an API key for the sandbox environment, simply create an account and generate a new key in settings - it only takes a few seconds.


Get an API key

Once you have generated your API key, record it in a secure place.

2. Decide Where to Send Funds From

You can choose to originate a payout from either your master wallet or any other wallet you have control over.

If you are using an omnibus account model where all your funds reside on your master wallet then using it to fund payouts makes complete sense. If you don't provide a source object when using the create payout endpoint, we will attempt to fund the payout from your master wallet.

If you have sub-wallets representing individual users or any other type of structure and you wish to use one of them as source for the payout, then determine the id of the desired wallet and specify it on the source object when using the create payout endpoint.

📘

Identity Verification

If the wallet originating a payout is associated to one of your customers, then issuing a payout from it requires end customer identification. Please reach out to support to understand the options available to you.

📘

Fees

Irrespective of the funding / source wallet scenario chosen, the fee associated with the payout is always deducted from your master wallet.

3. Fund Your Source Wallet

Once you have determined which wallet will fund your payout, make sure you have enough funds on it. You can learn more about different funding options here.

4. Create the Bank Account You Will Send the Payout To

Now make an API call to create the bank account you intend to send the payout to by using the create bank account for wire transfers endpoint. Use your API key from step 1.

# Replace ${YOUR_API_KEY} with the API key obtained on step 1
curl -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H "Authorization: Bearer ${YOUR_API_KEY}" \
    -X POST --url https://api-sandbox.circle.com/v1/banks/wires \
    --data '{"idempotencyKey":"6ae62bf2-bd71-49ce-a599-165ffcc33680", "walletId":"${YOUR_WALLET_ID}","beneficiaryName":"John Smith", "accountNumber":"123456789", "routingNumber":"021000021", "billingDetails":{"name":"John Smith", "city":"Boston", "country":"US", "line1":"1 Main Street", "district":"MA", "postalCode":"02201"}, "bankAddress":{"country":"US"}}'

You should receive a response like below.

{
  "data":{
    "id":"a6ba73a8-cc77-46c5-bbbc-ce7a97ecb372",
    "description":"JPMORGAN CHASE BANK, NA ****6789",
    "billingDetails":{
      "district":"MA",
      "country":"US"
    },
    "bankAddress":{
      "bankName":"JPMORGAN CHASE BANK, NA",
      "city":"NEW YORK",
      "district":"NEW YORK",
      "country":"US"
    },
    "createDate":"2020-07-27T07:22:53.120Z",
    "updateDate":"2020-07-27T07:22:53.120Z"
  }
}

📘

Bank Accounts for Wire Transfers in Different Countries

Note that the example above used option 1 of the set of fields required by the create bank account for wire transfers endpoint which is specific to U.S. domiciled bank accounts. For more details on other options (for bank accounts in other countries) see the guide on bank accounts for wire transfers in different countries.

5. Send the Payout

Now that your source wallet has funds and you have created a bank account to transfer funds to, you can use the create payout endpoint to initiate the transfer of funds.

If you are transferring funds from your master wallet, you don't need to supply a source object. The request would look like below.

# Replace ${YOUR_API_KEY} with the API key obtained on step 1
# Replace ${BANK_ACCOUNT_ID} with the id of the bank account you created earlier
curl -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: Bearer ${YOUR_API_KEY}' \
    -X POST --url https://api-sandbox.circle.com/v1/payouts \
    --data '{"idempotencyKey":"ff9d668a-ccde-48c3-82fd-8deb2a6f7c28", "destination":{"type":"wire", "id":"${BANK_ACCOUNT_ID}"}, "amount":{"currency":"USD", "amount":"150.00"}, "metadata": {"beneficiaryEmail":"[email protected]"}}'

If you are transferring funds from an arbitrary wallet, they you need to identify it in the source object like below.

# Replace ${YOUR_API_KEY} with the API key obtained on step 1
# Replace ${WALLET_ID} with the id of the wallet that will originate the transfer
# Replace ${BANK_ACCOUNT_ID} with the id of the bank account you created earlier
curl -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: Bearer ${YOUR_API_KEY}' \
    -X POST --url https://api-sandbox.circle.com/v1/payouts \
    --data '{"idempotencyKey":"ff9d668a-ccde-48c3-82fd-8deb2a6f7c28", "source":{"type":"wallet", "id":"${WALLET_ID}"}, "destination":{"type":"wire", "id":"${BANK_ACCOUNT_ID}"}, "amount":{"currency":"USD", "amount":"150.00"}, "metadata": {"beneficiaryEmail":"[email protected]"}}'

In either case, you should receive a response like below.

{
  "data":{
    "id":"2f0d9c44-c86d-4c1a-a33c-d436b8148879",
    "sourceWalletId":"1000005019",
    "createDate":"2020-07-27T07:59:09.350Z",
    "updateDate":"2020-07-27T07:59:09.350Z",
    "destination":{
      "type":"wire",
      "id":"a6ba73a8-cc77-46c5-bbbc-ce7a97ecb372",
      "name":"JPMORGAN CHASE BANK, NA ****6789"
    },
    "amount":{
      "amount":"150.00",
      "currency":"USD"
    },
    "status":"pending"
  }
}

🎉 Congrats, you sent your first payout to a bank account!

📘

Status of the Payout

The initial status of a payout is pending. You can obtain the most recent status of your payout by using the get payout endpoint.

Once the payout has been processed by Circle the status will move to complete and a tracking reference code will become available at the trackingRef property. If the payout failed to be sent, then the status will be updated to failed and you should look for a failure reason on the errorCode property.

6. Ready for the next step?

By sending a payout, you have covered one of the key primitives of the Circle Payments API.

If you are in advanced stages of experimenting with our APIs and want to plan moving to production, please start by applying for a business account and subsequently reach out to sales. We'll be happy to walk you through to the next steps.

We can't wait to see what you are going to build!

Updated 10 days ago



✨ Wire Payouts Quickstart


Get started with Circle Payments API and send your first wire payout in just a few minutes!

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.