Banking Guide
Overview
An account holds its fiat money in bank accounts: deposit accounts that BlockWyre opens for it at the bank your workspace uses. Each bank account has an account number that payers send money to, and the account's balance follows what arrives and what leaves. This guide covers the path from opening a bank account to receiving a deposit and sending money out.
Every call in this guide takes either kind of API key. On /v3, a workspace-scoped key names the account with account_id; an account-scoped key acts for its own account. On /api/v2, both kinds send accountId: in the body of the counterparty, withdrawal and bank-account calls, and in the path of the deposit instructions. An account-scoped key sends its own, and naming another account answers 403. See Key types and permissions.
1. Open a bank account
- Before: the account holder's KYC (individual) or KYB (business) verification is approved. The bank only opens accounts for holders it knows.
- Endpoint:
POST /v3/bank-accounts, with thecurrencyand anIdempotency-Key. - Result: the bank opens the account while the request waits, and the response carries its
account_number. The first bank account an account holds in a currency becomes its default: money in that currency that names no bank account lands there.
v2's POST /api/v2/banking/bank-accounts also opens one, asynchronously: it answers at once, and the deposit instructions are available once the bank has opened the account.
List Bank Accounts shows every bank account an account holds, with with_balance=true for what each holds.
2. Share the deposit instructions
- Endpoint:
GET /v3/bank-accounts/{bank_account_id}/deposit-instructions, for one bank account. - Result: what a payer needs to send money into that bank account: its own account number, the routing number, SWIFT code, bank name and address, and the beneficiary name. A bank account that is not
activeanswers409 deposit_instructions_not_available.
v2's GET /api/v2/banking/deposit-instructions/{accountId} answers one set of instructions for the whole account, with the number of only one of its bank accounts, and 204 No Content while the account has none.
3. Receive a deposit
- Action: the payer sends an ACH or wire transfer from their bank to the account number.
- Webhook: when the deposit is recorded,
bank_transaction_createdis sent withdetails.typeset todeposit. Each later change of status is sent asbank_transaction_status_updated. See Banking Webhooks. - Result: the deposit appears in the account's transactions (
GET /api/v2/transactions,transactionType=bank) and in its balances (GET /v3/balances).
To pull money in from the holder's own account at another US bank instead of waiting for a transfer, use an ACH pull.
4. Send money out
- Save the destination bank account as a counterparty. A US account — ACH, a domestic wire, or an international wire — is
POST /v3/banking/counterparties. Mexico, Colombia, Argentina, Brazil and Nigeria stay on their v2 pages, for examplePOST /api/v2/banking/counterparties/mx. A counterparty saved on v3 is the same record the withdrawal below pays. - Preview the withdrawal with
POST /api/v2/banking/withdrawal-previewto see the fee. - Execute it with
POST /api/v2/banking/withdrawal. The same webhooks follow it, withdetails.typeset towithdraw:bank_transaction_created, thenbank_transaction_status_updated.
Sequence Diagram
Support and Resources
If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.
Stay Updated
Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:
- Instagram: BlockWyre Instagram
- Twitter: BlockWyre Twitter
- Facebook: BlockWyre Facebook
- LinkedIn: BlockWyre LinkedIn
We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!