Skip to main content

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 the currency and an Idempotency-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 active answers 409 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_created is sent with details.type set to deposit. Each later change of status is sent as bank_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​

  1. 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 example POST /api/v2/banking/counterparties/mx. A counterparty saved on v3 is the same record the withdrawal below pays.
  2. Preview the withdrawal with POST /api/v2/banking/withdrawal-preview to see the fee.
  3. Execute it with POST /api/v2/banking/withdrawal. The same webhooks follow it, with details.type set to withdraw: bank_transaction_created, then bank_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:

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!