Link bank accounts, deposit fiat, and withdraw stablecoins through wire transfers
Link your end customers’ bank accounts to their Digital Asset Accounts so they
can move money between traditional banking and stablecoins. Wire deposits
convert fiat into stablecoins. Wire withdrawals redeem stablecoin balances and
send funds to the linked bank account.These steps apply to custodial and non-custodial accounts. Non-custodial
accounts receive wire deposits through the same steps, and Circle converts a USD
deposit to USDC, or a EUR deposit to EURC, and credits it to the account. Only
the withdrawal in Step 5 differs, so choose the tab for your account type there.
Prerequisites
Before you begin, ensure that you’ve:
Obtained an API key for Digital Asset Accounts from Circle.
Onboarded an end customer with an active account and its accountId.
Reviewed whether Strong Customer Authentication (SCA) applies. Circle requires
SCA headers on withdrawals and when linking wire accounts for end customers in
the European Economic Area (EEA). See
Implement SCA.
Run a device check for the end customer and kept the deviceId it returns.
Every money movement and bank account request carries it in riskSignals. See
Collect device risk signals.
For a non-custodial account, created the account and a DaaUserClient for the
end customer, and set up your backend relay. See
Create a non-custodial account.
Installed cURL on your development machine.
Steps
Step 1. Link a bank account
Link your end customer’s bank account by providing the bank details and billing
information.
For end customers in the European Economic Area (EEA), EUR funding uses the same
wire flow. Provide the account’s iban instead of accountNumber and
routingNumber. EUR deposits mint EURC.
{ "data": { "trackingRef": "CIR3XXXYYY", "beneficiary": { "name": "Circle Internet Financial Inc", "address1": "99 High Street", "address2": "Boston, MA 02110" }, "virtualAccountEnabled": false, "beneficiaryBank": { "name": "Silicon Valley Bank", "routingNumber": "121140399", "accountNumber": "1234567890", "currency": "USD", "country": "US" } }}
The trackingRef is a unique reference code that identifies the wire deposit.
Your customer must include it in their wire transfer so Circle can match the
payment to the correct account.
Your end customer must include the trackingRef when sending the wire transfer.
Without this reference, the deposit cannot be matched to the correct account.
Step 3. Deposit fiat (sandbox simulation)
In the sandbox environment, simulate a wire deposit using the mock payments
endpoint. In production, your end customer sends a real wire transfer using the
instructions from the previous step.
The withdrawal processes asynchronously. Monitor the status by polling the
withdrawals endpoint or by setting up
webhook notifications.If the source account has insufficient funds, the API returns an error:
{ "code": 2, "message": "Insufficient funds. The source account does not have enough balance to complete this withdrawal."}
Verify the account balance before initiating a withdrawal.
Non-custodial accounts are available in sandbox only. Production non-custodial
accounts are on the roadmap.
Create the withdrawal with the SDK in your application. Your backend links the
bank account in Step 1, the same way as for a custodial account. The end
customer’s device asks them to confirm with biometrics, or the screen lock on an
iPhone, before the SDK signs the request:
import { randomUUID } from "expo-crypto";import type { WithdrawalDetail } from "@circle-fin/daa-react-native-sdk";// Store the key before you send the request, so a retry can reuse it.const idempotencyKey: string = randomUUID();const withdrawal: WithdrawalDetail = await user.withdrawals.create({ idempotencyKey, source: { type: "account", id: account.accountId }, destination: { type: "wire", id: wireAccountId }, amount: { amount: "5000.00", currency: "USD" }, riskSignals: { ipAddress: endUserIp, sessionId, deviceId },});
user is the DaaUserClient and account is the non-custodial account from
Create a non-custodial account.
wireAccountId is the id from Step 1. Include riskSignals on every transfer
and withdrawal. Circle can reject a withdrawal without them. The SDK signs the
request body in your application, so your backend can’t add riskSignals
afterward. Get the end customer’s ipAddress and sessionId from your backend,
and the deviceId from the device check in the prerequisites.Expected result: the end customer confirms the prompt, and
withdrawal.status.kind is pending.Circle moves the funds from the non-custodial account to a custodial account and
then pays out to the bank. If the payout fails, Circle returns the funds to the
original non-custodial account.The withdrawal processes asynchronously. Read it with
user.withdrawals.get(withdrawal.id) until its status.kind is complete or
failed.Handle transport and idempotency_conflict errors the same way as for a
transfer, and find the original with user.withdrawals.list({ accountId }). See
Send crypto transfers.
List and retrieve wire accounts
You can query linked wire accounts at any time.List all wire accounts for an end customer