BlockonomicsAPI Reference

Payer API

The payer's half of Payment Intents. Public endpoints called with only the intent ID, no API key: check what is due, get a BTC or USDT address and amount, and submit USDT transaction hashes. Built for browsers and AI agents.

3 endpoints

Endpoints

GET/v2/pay_stat/{id}

Get payment status

Returns what is left to pay on a payment intent and the cryptos it can be paid with. No API key: the intent ID is the payer's only credential, so a browser or an AI agent can call

POST/v2/pay/{id}

Create a payment quote

Prices the intent's dueamount in the chosen crypto and returns the address to pay and the exact amount, at a price locked for 5 minutes. No API key needed.

POST/v2/pay/{id}/submit

Submit a transaction hash

Links a USDT transaction to the intent's open USDT quote. Required for every USDT payment: all USDT quotes on a store share its wallet address, so the transaction hash is the only

object

The payment_status object

The payer's view of a payment intent: how much is left to pay and which cryptos the store accepts.

Attributes

idstring

ID of the payment intent.

amountstring

Total amount in currency.

currencystring

Fiat currency code.

statusstring

unpaid: no payment detected. processing: a payment is detected but not confirmed yet. underpaid: confirmed payments cover part of amount and nothing else is in progress. paid: confirmed payments cover amount. Fulfil the order only on paid.

Allowed: unpaidprocessingunderpaidpaid

due_amountstring

Amount still to pay in currency. If it is above 0.00, create a quote for it. If it is 0.00 and status is processing, wait for confirmation.

created_atinteger

When the intent was created, as a Unix timestamp in seconds.

accepted_cryptosarray of strings

Cryptos the store accepts. Pass one as crypto when creating a quote.

testmodeboolean

Whether the store is in test mode. Test-mode addresses cannot receive real funds.

Example object

{
  "id": "pi_5GfD5m1b8khzFSLza91VR6",
  "amount": "10.00",
  "currency": "USD",
  "status": "processing",
  "due_amount": "5.01",
  "created_at": 1793615164,
  "accepted_cryptos": [
    "BTC",
    "USDT"
  ],
  "testmode": false
}
object

The payment_quote object

A payment intent's due amount priced in one crypto, with the address to pay and a 5-minute price lock. Paid quotes are listed as the intent's payments.

Attributes

idstring

Unique ID, starting with pq_.

amountstring

Fiat amount this quote covers, in the intent's currency. This is the intent's due_amount when the quote was created.

crypto_amountstring

Amount to send, in the crypto's base units: satoshis for BTC (8 decimals), 6 decimals for USDT. A string so large values keep their precision.

paid_crypto_amountstring

Amount received, in base units. "0" until a payment is detected. Can be less or more than crypto_amount.

cryptostring

Crypto to pay in.

Allowed: BTCUSDT

addressstring

Address to send crypto_amount to. Each BTC quote has its own address. USDT quotes use the store's USDT wallet address.

statusstring

pending: waiting for payment. unconfirmed: payment detected, no confirmations yet. partially_confirmed: payment has confirmations but is not final. confirmed: payment is final and credited to the intent. failed: the USDT transaction reverted on-chain and is not credited.

Allowed: pendingunconfirmedpartially_confirmedconfirmedfailed

txidstring

Hash of the payment transaction. null until a payment is detected or, for USDT, its hash is submitted.

expires_timestampinteger

When the price lock ends, as a Unix timestamp in seconds. Once it has passed, create a quote again before paying.

paid_timestampinteger

When the payment's latest status change was recorded, as a Unix timestamp in seconds. null until a payment is detected.

Example object

{
  "id": "pq_8GgAyuReWzLbJtEQrTNaT5",
  "amount": "10.00",
  "crypto_amount": "12966",
  "paid_crypto_amount": "0",
  "crypto": "BTC",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "status": "pending",
  "expires_timestamp": 1793615475
}