AbsolutePayDocs

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 need onramp: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/banks and wait for approved.
  • 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

StatusMeaning
CREATINGWe are creating the order; it resolves on its own within minutes.
PENDINGWaiting for your transfer.
PROCESSINGYou confirmed; the transfer is being checked.
SUCCESSCredited.
CANCELLEDCancelled before payment (or the instructions lapsed).
FAILEDThe 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

CodeWhen
422 bank_not_approvedThe bank account is not yours or not approved.
404 quote_not_found / 409 quote_expiredUnknown, someone else's, or lapsed quote — quote again.
409 quote_usedThat quote already created an order.
409 not_awaiting_payment / not_cancellableConfirm/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.

On this page