Skip to content
Last updated

Bank Transfer

For the complete documentation index, see llms.txt. Append .md to any page URL for its markdown version.

Bank transfers are fully API-driven. There is no SDK involved — your backend creates the ramp, and the API returns payment instructions for the user to complete the transfer. This makes bank transfer the simplest Native API integration path: no platform setup, no payment sheet.

This guide covers on-ramp (fiat → crypto) and off-ramp (crypto → fiat) via bank transfer. Identity creation, KYC, eligibility, and pricing are covered in the Integration Guide — start there if you haven't set those up yet. This guide picks up from paymentReady: true.


On-ramp (buy crypto)

Create the ramp

Once your backend confirms paymentReady: true, create the ramp with POST /eapi/v0/ramps. Pass the fiat currency, payment method, crypto asset, blockchain, and the wallet address that receives the crypto. Set either fiatAmount or cryptoAmount — not both.

POST /eapi/v0/ramps
Content-Type: application/json

{
  "identityReference": "partner-abc123",
  "source": {
    "fiat": {
      "id": "AUD",
      "method": "payid-bank-transfer"
    }
  },
  "target": {
    "crypto": {
      "id": "USDT",
      "blockchain": "TRON",
      "walletAddress": "TYDzsYUEpvnYmQk4zGP9sWWcTEd2MiAtW6"
    }
  },
  "fiatAmount": "500.00"
}

Use the same identityReference you used for eligibility.

Display payment instructions

The response includes sourceDepositInstructions — the details the user needs to complete the bank transfer. Display these in your UI.

{
  "id": "b7f1ffbb2f1bd7a5e2ba152b4049d234",
  "status": "INITIALIZED",
  "source": {
    "fiat": { "id": "AUD", "method": "payid-bank-transfer" },
    "amount": "500.00"
  },
  "target": {
    "crypto": {
      "id": "USDT",
      "blockchain": "TRON",
      "walletAddress": "TYDzsYUEpvnYmQk4zGP9sWWcTEd2MiAtW6"
    },
    "amount": "324.51"
  },
  "sourceDepositInstructions": {
    "recipientEmail": "[email protected]",
    "depositReference": "BNX-12345678"
  },
  "receipt": {
    "gatewayFee": "2.50",
    "networkFee": "2.00",
    "sourceAmount": "500.00",
    "targetAmount": "324.51"
  },
  "createdAt": "2026-04-17T03:45:00.000Z"
}

The instruction fields vary by payment method — for PayID, recipientEmail and depositReference are returned. The user sends the transfer from their bank, using the deposit reference so Banxa can match the payment.

Reference is required

Instruct users to include the depositReference when making the transfer. Without it, Banxa cannot match the payment to the transaction.


Off-ramp (sell crypto)

Create the ramp

Once your backend confirms paymentReady: true, create the ramp with POST /eapi/v0/ramps. Pass the crypto asset, blockchain, and the user's sending wallet address, then the fiat currency, payout method, and the user's bank account details. Set either fiatAmount or cryptoAmount — not both.

POST /eapi/v0/ramps
Content-Type: application/json

{
  "identityReference": "partner-abc123",
  "source": {
    "crypto": {
      "id": "USDT",
      "blockchain": "TRON",
      "walletAddress": "TYDzsYUEpvnYmQk4zGP9sWWcTEd2MiAtW6",
      "walletAddressMemo": null
    }
  },
  "target": {
    "fiat": {
      "id": "AUD",
      "method": "payid-bank-transfer",
      "instructions": {
        "accountName": "Jane Smith",
        "accountNumber": "12345678",
        "bsb": "063123"
      }
    }
  },
  "cryptoAmount": "100.00"
}

Use the same identityReference you used for eligibility. The request has the same shape as an on-ramp with source and target swapped, plus fields that only apply to off-ramps:

FieldRequiredNotes
identityReferenceYesMax 100 characters.
source.crypto.id / source.crypto.blockchainYesThe asset and network the user sends.
source.crypto.walletAddressYesThe user's sending wallet (on an on-ramp, target.crypto.walletAddress is the receiving wallet). Banxa screens it and uses it as the refund address. Max 255 characters.
source.crypto.walletAddressMemoIf the wallet uses oneMemo or tag of the user's sending wallet. Not echoed back: walletAddressMemo in the response is Banxa's deposit memo.
target.fiat.id / target.fiat.methodYesThe payout currency and method. See Payout methods.
target.fiat.instructionsYes (Interac: send {})Off-ramp only. The user's bank account details, as a single object (not an array).
target.fiat.tosAcceptedACH onlyOff-ramp only. Only true is accepted; leave it out otherwise (false returns a 422). See ACH terms of service.
fiatAmount or cryptoAmountExactly oneStrings. Sending both, or neither, is rejected.

Payout methods

FiatPayout methodmethodRequired instructions fields
AUDBank transfer (NPP) to a BSB and account numberpayid-bank-transferaccountName, accountNumber, bsb
EURSEPAsepa-bank-transferaccountName, iban
CADInteracinterac-bank-transferNone. Send instructions as an empty object ({}); leaving it out currently fails with a 500. Paid by Interac e-Transfer to the email address on the customer's Banxa account.
USDACHach-bank-transferbankName (max 200 characters), accountName (max 200 characters), accountNumber, routingNumber (a 9-character string, not a number)

See Supported payment methods for the region each method covers. The same instructions fields apply when you create the ramp from a quote.

ACH terms of service

ACH payouts go through a provider whose terms of service the user must accept once. If the user hasn't accepted them yet, show them the terms and send "tosAccepted": true in target.fiat (at the top level when you create the ramp from a quote). Otherwise the request is rejected with a 422. See Regulatory agreements.

Display the deposit address

The response includes sourceDepositInstructions — Banxa's crypto deposit address for this ramp. Display it in your UI. Once Banxa receives the crypto, the fiat payout is initiated.

{
  "id": "c8g2ggcc3g2ce8b6f3cb263b5150e345",
  "status": "INITIALIZED",
  "source": {
    "crypto": {
      "id": "USDT",
      "blockchain": "TRON",
      "walletAddress": "TYDzsYUEpvnYmQk4zGP9sWWcTEd2MiAtW6",
      "walletAddressMemo": null
    },
    "amount": "100.00"
  },
  "target": {
    "fiat": { "id": "AUD", "method": "payid-bank-transfer" },
    "amount": "150.20"
  },
  "sourceDepositInstructions": {
    "walletAddress": "TBanxaDepositAddress123456",
    "walletAddressMemo": null
  },
  "receipt": {
    "sourceTransactionHash": null,
    "gatewayFee": "2.50",
    "networkFee": "1.00",
    "sourceAmount": "100.00",
    "targetAmount": "150.20"
  },
  "createdAt": "2026-04-17T03:45:00.000Z",
  "updatedAt": "2026-04-17T03:45:00.000Z",
  "expiredAt": "2026-04-17T04:50:00.000Z",
  "completedAt": null
}

status is always INITIALIZED in the create response. source.crypto.walletAddress echoes the user's sending wallet; the deposit address is sourceDepositInstructions.walletAddress. expiredAt is when the deposit window closes. Some payout methods add extra fields to sourceDepositInstructions — ignore any you don't need.

sourceDepositInstructions.walletAddressMemo is always present. It is null unless the network needs a memo or destination tag (for example XRP or XLM). When it isn't null, the user must include it, or the deposit can't be matched to the ramp.

The deposit address can be empty at creation

For some assets the deposit address is generated shortly after the ramp is created, so sourceDepositInstructions.walletAddress can be empty in the create response. Wait for the COIN_DEPOSIT_READY webhook, or poll GET /eapi/v0/ramps/{id}, before showing the deposit address.

Send the crypto

Your app or backend builds, signs, and broadcasts the transfer to the deposit address. Banxa never signs or initiates the transaction. Make sure the transfer:

  • Is exactly the ramp's source.amount, of the right asset, on the right network.
  • Includes the walletAddressMemo, if one was returned.
  • Is sent before expiredAt.
  • Comes from the walletAddress given at creation. Banxa detects the deposit from the balance of the deposit address, so a deposit from another wallet is still credited, but the declared wallet is the one that is screened and used for any refund.

See Deposit issues and refunds for what happens when a deposit doesn't match.

Retrying a failed request

There is no idempotency key and no cancel endpoint for ramps. If a create request times out or fails without a response, call GET /eapi/v0/ramps to check whether the ramp was created before you retry. Otherwise you may create duplicate ramps, each with its own deposit address.


Locking the exchange rate

Optionally, lock the exchange rate before creating the ramp. Get a quote first:

GET /eapi/v0/quote?identityReference=partner-abc123&fiat=AUD&crypto=USDT&blockchain=TRON&method=payid-bank-transfer&transactionType=ONRAMP&fiatAmount=500

The response includes a quoteId valid for 3 minutes. Pass it in your ramp creation request:

{
  "identityReference": "partner-abc123",
  "quoteId": "q_abc123xyz",
  "walletAddress": "TYDzsYUEpvnYmQk4zGP9sWWcTEd2MiAtW6"
}

The source, target, and amount are inferred from the quote — you don't repeat them in the request body. The identityReference must match the one used for the quote.

For an off-ramp, get the quote with transactionType=OFFRAMP and the payout method:

GET /eapi/v0/quote?identityReference=partner-abc123&fiat=AUD&crypto=USDT&blockchain=TRON&method=payid-bank-transfer&transactionType=OFFRAMP&cryptoAmount=100

Then send the user's bank details as a top-level instructions object, with the same fields as in Payout methods. walletAddress is the user's sending wallet. For ACH, also send a top-level tosAccepted if needed:

{
  "identityReference": "partner-abc123",
  "quoteId": "q_abc123xyz",
  "walletAddress": "TYDzsYUEpvnYmQk4zGP9sWWcTEd2MiAtW6",
  "walletAddressMemo": null,
  "instructions": {
    "accountName": "Jane Smith",
    "accountNumber": "12345678",
    "bsb": "063123"
  }
}
quoteId support

The quoteId is currently only accepted by POST /eapi/v0/ramps. If you are building a card or mobile wallet flow, use indicative pricing (GET /eapi/v0/price) instead.


Tracking transaction status

Bank transfers are asynchronous — the user completes the transfer independently, and processing takes time. Configure a webhook endpoint to receive status updates, or poll using GET /eapi/v0/ramps/{id}.

Typical on-ramp lifecycle: INITIALIZED → AWAITING_FUNDS → FUNDS_RECEIVED (fiat received) → PAYMENT_SUBMITTED (crypto sent) → COMPLETED

Typical off-ramp lifecycle: INITIALIZED → AWAITING_FUNDS → FUNDS_RECEIVED (crypto received) → PAYMENT_SUBMITTED (fiat payout sent) → COMPLETED

A ramp that expires, is declined, or needs extra verification shows as CANCELLED when polled. See Webhooks for the event sequence, the full payload schema, and how ramp statuses map to webhook events.


Deposit issues and refunds (off-ramp)

SituationWhat happens
Deposit windowSet per payout method, typically 60 minutes plus a short buffer. Use the ramp's expiredAt rather than hard-coding it.
Deposit seen on-chain but not yet confirmed when the window closesThe ramp is not expired; Banxa waits for confirmation.
Exact amount receivedConfirmed automatically, and the payout continues.
UnderpaidThe deposit window is extended once: the ramp goes back to AWAITING_FUNDS and COIN_DEPOSIT_READY is sent again, so the user can top up. If it's still short, Banxa Support handles it manually.
OverpaidBanxa Support handles it manually.
Wrong asset or wrong networkNot handled automatically. Contact Banxa Support with the ramp ID and transaction hash.
Missing memo or tagThe deposit can't be matched automatically. Contact Banxa Support.
Deposit after the ramp expiredNot picked up automatically. Contact Banxa Support with the ramp ID and transaction hash.

Crypto refunds are handled by Banxa Support and sent to the user's declared source.crypto.walletAddress. Refunds can't be requested through the API; contact Banxa Support.