For the complete documentation index, see llms.txt. Append
.mdto 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.
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.
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.
Instruct users to include the depositReference when making the transfer. Without it, Banxa cannot match the payment to the transaction.
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:
| Field | Required | Notes |
|---|---|---|
identityReference | Yes | Max 100 characters. |
source.crypto.id / source.crypto.blockchain | Yes | The asset and network the user sends. |
source.crypto.walletAddress | Yes | The 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.walletAddressMemo | If the wallet uses one | Memo 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.method | Yes | The payout currency and method. See Payout methods. |
target.fiat.instructions | Yes (Interac: send {}) | Off-ramp only. The user's bank account details, as a single object (not an array). |
target.fiat.tosAccepted | ACH only | Off-ramp only. Only true is accepted; leave it out otherwise (false returns a 422). See ACH terms of service. |
fiatAmount or cryptoAmount | Exactly one | Strings. Sending both, or neither, is rejected. |
| Fiat | Payout method | method | Required instructions fields |
|---|---|---|---|
| AUD | Bank transfer (NPP) to a BSB and account number | payid-bank-transfer | accountName, accountNumber, bsb |
| EUR | SEPA | sepa-bank-transfer | accountName, iban |
| CAD | Interac | interac-bank-transfer | None. 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. |
| USD | ACH | ach-bank-transfer | bankName (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 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.
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.
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.
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
walletAddressgiven 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.
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.
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=500The 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=100Then 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"
}
}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.
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.
| Situation | What happens |
|---|---|
| Deposit window | Set 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 closes | The ramp is not expired; Banxa waits for confirmation. |
| Exact amount received | Confirmed automatically, and the payout continues. |
| Underpaid | The 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. |
| Overpaid | Banxa Support handles it manually. |
| Wrong asset or wrong network | Not handled automatically. Contact Banxa Support with the ramp ID and transaction hash. |
| Missing memo or tag | The deposit can't be matched automatically. Contact Banxa Support. |
| Deposit after the ramp expired | Not 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.