Bank deposit
Fund your balance by bank transfer — USD in, USDT or USDC credited.
A bank deposit (on-ramp) turns a USD bank transfer into USDT or USDC on your balance. The flow:
quote → create the order → wire the money → confirm with the receipt → credited. The credit arrives
asynchronously and is announced with the onramp.succeeded webhook (onramp.failed if the
transfer could not be matched).
Before you start:
- Creating, confirming and cancelling need
onramp:write; reads needonramp:read. These are their own scopes — a payments key does not reach bank deposits; add them to the key explicitly. - The transfer must come from one of your own bank accounts that has been approved. Bank accounts are
shared with the off-ramp: register one with
POST /v1/offramp/banksand wait forapproved. - Bank deposits are available to registered companies only (a business account); for an individual
account every bank-deposit endpoint returns
403 business_only. - Your account must have completed level 2 verification (otherwise
403). - Supported today: wire USD, receive USDT or USDC.
1. Your bank accounts
curl https://api.absolutepay.io/v1/onramp/banks -H "Authorization: Bearer $AP_KEY"Use the bankAccountId of an account whose status is approved.
2. Quote
Quote by what you will wire (fiatAmount) or by what you want credited (cryptoAmount) — exactly one.
curl https://api.absolutepay.io/v1/onramp/quote \
-H "Authorization: Bearer $AP_KEY" -H "Content-Type: application/json" \
-d '{ "cryptoCurrency": "USDT", "fiatCurrency": "USD", "fiatAmount": "1000", "bankAccountId": "2897434" }'{ "quoteToken": "qt_01JX…", "validPeriod": 60, "fiatAmount": "1000", "cryptoAmount": "989.12",
"fiatRate": "1", "tradeFee": "10.88", "feeCurrency": "USD", "cryptoCurrency": "USDT", "fiatCurrency": "USD" }Quotes are short-lived (validPeriod seconds). Each quote can create one order.
3. Create the order
The order takes only the quote and the bank account it was priced for — the amounts are the quote's.
Send an Idempotency-Key so a retry is safe.
curl https://api.absolutepay.io/v1/onramp/orders \
-H "Authorization: Bearer $AP_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "quoteToken": "qt_01JX…", "bankAccountId": "2897434" }'The 201 response is the order in PENDING with the wire instructions:
{
"id": "onr-…", "orderId": "79550727153516601", "status": "PENDING",
"fiatAmount": "1000", "fiatCurrency": "USD", "cryptoAmount": "989.12", "cryptoCurrency": "USDT",
"payTo": { "accountName": "…", "bankName": "…", "iban": "…", "swift": "…", "bankAddress": "…" },
"transferRemark": "PCC1018…"
}Wire exactly fiatAmount to payTo and put transferRemark on the transfer as the reference, so
it can be matched.
4. Confirm the transfer
Once the wire is sent, confirm with the receipt (jpg, png or pdf, up to 4 MB, base64):
curl https://api.absolutepay.io/v1/onramp/orders/onr-…/confirm \
-H "Authorization: Bearer $AP_KEY" -H "Content-Type: application/json" \
-d '{ "receipt": { "filename": "receipt.pdf", "contentType": "application/pdf", "dataBase64": "JVBERi0…" } }'The order moves to PROCESSING while the transfer is checked, then to SUCCESS (the crypto is on your
balance and shows in /v1/transactions as ONRAMP) or FAILED.
To abandon an order before you wire, POST /v1/onramp/orders/{id}/cancel (only while PENDING).
Statuses
| Status | Meaning |
|---|---|
CREATING | We are creating the order; it resolves on its own within minutes. |
PENDING | Waiting for your transfer. |
PROCESSING | You confirmed; the transfer is being checked. |
SUCCESS | Credited. |
CANCELLED | Cancelled before payment (or the instructions lapsed). |
FAILED | The order could not be created or the transfer was not accepted (errorMessage). |
Track orders with GET /v1/onramp/orders (filter status, search q, keyset paging) or
GET /v1/onramp/orders/{id}; listen for onramp.succeeded / onramp.failed, whose orderRef is the
order's orderId.
Errors
| Code | When |
|---|---|
422 bank_not_approved | The bank account is not yours or not approved. |
404 quote_not_found / 409 quote_expired | Unknown, someone else's, or lapsed quote — quote again. |
409 quote_used | That quote already created an order. |
409 not_awaiting_payment / not_cancellable | Confirm/cancel on an order that is no longer PENDING. |
Test mode
With a test key the whole loop runs without money: the order answers with sandbox wire instructions, and
confirming with any receipt credits the test balance a moment later and sends onramp.succeeded.