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

1. Get an API key

The Circle Payouts 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.

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","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

You can obtain the most recent status of your payout by using the get payout endpoint or through notifications.

Status Definitions:
Pending: Circle is currently processing the payout request from the customer. This is status is set when the payout is created.

Complete: Circle has successfully sent the payout and received confirmation from our partner bank. When the status is complete the trackingRef will also be assigned.
NOTE: There is no guarantee that payment will be settled and funds will be available to the beneficiary, Complete status only indicates that payment has been successfully sent to our partner bank which can be rejected by payment rails or processing bank.

Failed: Unsuccessful payout request. Reason for error can be found in the errorCode and/or the riskEvaluation. The payout could incur fees if rejected by the network.

Complete w/ return object: Payout was returned to Circle after it was previously marked as complete. In this instance, Circle will credit the original payout amount back to the payout source wallet. The payout status will remain as complete, however an additional return object will be shown in the original payout response. You will also receive a returns notification informing you of this event.

6. Ready for the next step?

By sending a payout, you have covered one of the key primitives of the Circle Payouts 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 Circle 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!