Base URL
All API requests go to:Every response uses the same envelope: a
data object on success, or an error object on failure. See Errors for the full list of error codes.Payment lifecycle
Every payment moves through a predictable set of statuses:| Status | Description |
|---|---|
pending | Payment created, waiting for the buyer to send funds |
detected | Funds seen on-chain, awaiting required confirmations |
completed | Payment confirmed; your balance has been credited |
overpaid | Buyer sent more than the expected amount |
underpaid | Buyer sent less than the expected amount |
expired | The 30-minute quote window elapsed with no payment |
failed | Payment failed for another reason |
cancelled | Payment was cancelled |
How a payment works
Create a payment or checkout session
Call
POST /payments with the fiat amount and the coin, or POST /checkout/sessions for a hosted checkout page where the buyer picks the coin.The buyer pays
Blockra returns a deposit
address, the exact expected_amount, and a qr_data string. Display these to the buyer. The quote is valid for 30 minutes.Blockra settles
Once the transaction reaches the required confirmations, the payment moves to
completed and your merchant balance is credited the net amount — the total minus the Blockra fee.You withdraw
Withdraw your available balance to an external wallet any time from the dashboard.
Amounts and precision
Crypto amounts are returned in two forms:expected_amount— a human-readable decimal string (e.g."0.1183"), already rounded to a payable precision. Show this to the buyer.expected_amount_atoms— the exact integer amount in the asset’s smallest unit (satoshis, wei, etc.) as a string. Use this for exact programmatic comparisons.
fiat_amount, fee_fiat, net_fiat) are decimal numbers in the payment’s currency.
Supported assets
| Asset | Network | Smallest unit | Decimals |
|---|---|---|---|
| BTC | Bitcoin | satoshi | 8 |
| LTC | Litecoin | litoshi | 8 |
| ETH | Ethereum | wei | 18 |
| USDC | Ethereum | micro-USDC | 6 |
| USDT | Ethereum | micro-USDT | 6 |
Fees
Blockra charges a fee on each payment, and a small fee on withdrawals:| Fee | |
|---|---|
| Per payment | 1.25% + $0.10 |
| Withdrawal (payout) | 0.5% |
net_fiat = fiat_amount − fee_fiat). On withdrawal, Blockra deducts the 0.5% payout fee plus the on-chain network fee, then sends the remainder to your external wallet.
The minimum payment is $1, or its equivalent in your pricing currency.
Next steps
Authentication
Create an API key and learn how to pass it on every request.
Accept Payments
Walk through a full payment integration end to end.