ACH Debits

Create a bank transfer

Changed on

Creates a new bank transfer using the walletId and bankAccountId as counterparties. Most details are inferred from bankAccountId. The walletId and bankAccountId must be owned by the same enterpriseId.

BitGo automatically collects the request's client IP and user agent. However, if the request is being made by your server instead of the client's device, you should collect the client IP and user agent and specify it in the body as part of the request. The IP and user agent will be used for risk evaluation.

Requires access token scope: wallet_spend_all

post/api/tradfi/v1/bank-transfers

Request

  • Base URL
    https://developers.bitgo.com
  • URL
    https://developers.bitgo.com/api/tradfi/v1/bank-transfers
  • Auth
    none declared

Request body

acceptAuthTermsboolean required

Whether the client has accepted the ACH authorization terms. Required for deposits (transferDirection: "in"). Must be true to initiate a deposit. See https://app.bitgo.com/my/ach-terms for institutional and retail clients, or https://app.bitgo.com/my/caas/ach-terms for CaaS.

amountstring

The absolute value of the total amount of funds to be transferred as a decimal string (e.g., "500.00" for $500 USD). Include decimal places where applicable. Mutually exclusive with baseAmount.

applyInstantCreditboolean

Whether to apply instant credit to the transfer.

bankAccountIdstring required

The bank account to use. Determines the bank rails. Presently, only ACH accounts are supported.

baseAmountstring

The transfer amount in the currency's smallest unit as a string (e.g., "50000" for $500.00 USD, where the base unit is cents). The value is converted to a decimal using the currency's unit precision (e.g., 2 for USD, 0 for JPY). Mutually exclusive with amount.

idstring required

Client-generated transfer ID. Serves as the idempotency key. Prefer UUID v4, v5, or v7.

ipAddressstring

Optional end-user IP address. Provide this when the request originates from your server. This is used for risk evaluation. The value must be a valid IPv4 or IPv6 address.

userAgentstring

Optional end-user user agent. Provide this when the request originates from your server. This is used for risk evaluation.

transferDirection'in' required
walletIdstring required

The Go Account wallet to use as counterparty.

Response

Created

amountstring required

The absolute value of the total amount of funds to be transferred to or from the related bank. Always returned as a decimal string with the currency's full precision (e.g., "500.00" for USD), regardless of whether the request used amount or baseAmount.

applyInstantCreditboolean required

Whether to apply "instant credit" to the transfer. This allows funds to be made available to customer from the CaaS reserve account if they are available.

bankAccountIdstring required

The bank account used for the transfer. This also determines the bank rails used for the transfer.

counterpartyobject nullable

Information about the counterparty of the transfer. The available fields vary by bank rail and region (e.g. name, financial institution, country). The counterparty account number is masked, exposing only the last four characters (e.g. "*****7890"). Null until counterparty details are available, typically once the transfer has settled.

createdAtstring date-time required

When the transfer was created/initiated.

enterpriseIdstring required

The enterprise related to the transfer. Determined automatically by the walletId.

estimatedEffectiveOnstring date nullable required

The date when the transfer is expected to become "effective" or "posted" by the related bank. Without instant credit this will usually be either T+1 or T+4 depending on risk profile of the related enterprise and bank account. Null when not yet determined.

idstring required

The ID of the transfer. This should be generated by the client (prefer v4, v5, or v7) because it also serves as the idempotency key. Using an automatically generated ID provides no idempotency guarantees.

instantCreditLiabilityboolean required

Whether the current transfer counts against the CaaS reserve for instant credit. Only applies to transfers that opted for applyInstantCredit and have not yet settled. Once settled, transitions to false.

memoIdstring required

An automatically generated memo used for matching with bank transfers. Informational only.

settledAtstring date-time nullable required

When the transfer was settled (posted by the bank). Null until status is settled.

status'initiated' | 'processing' | 'settled' | 'reversed' | 'failed' required

The status of a transfer. initiated means newly created and not yet completed processing. processing means currently processing with bank providers with funds in flight. settled means funds successfully processed and no longer flagged as instantCreditLiability. reversed means a previously settled transfer was reversed by the processor. failed means an unrecoverable error occurred before settlement.

transferDirection'in' required
transferType'ach-us' required
txidstring required

The transaction ID correlated with wallet platform. Can also be used in GET requests as an identifier.

walletIdstring required

The wallet (Go Account) used as counterparty to the transfer. Also determines the related enterprise.

Example response

{
  "counterparty": {
    "name": "Jane Doe",
    "accountNumber": "*****7890",
    "financialInstitution": "COBADEFFXXX",
    "country": "DE"
  }
}

Changes

  • 30741a6c8193Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property