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.
You should receive a response like below.
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.
If you are transferring funds from an arbitrary wallet, they you need to identify it in the `source` object like below.
In either case, you should receive a response like below.
🎉 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!