Find your keys in the dashboard under Stores, then your store, then API keys. Keys you type here stay in this browser tab; the tester sends only the signature, never the secret.
See the page your customers see
Open a test checkout, pick a coin and pay it with pretend money. It runs in test mode, so no real address is shown and nothing is sent.
ArionPay API
Create an invoice from your server with one signed request, send your customer to the checkout page, and get a signed webhook when the payment is confirmed. Customers pay straight to your own wallet. ArionPay stores only your extended public keys and cannot move your money.
1. Get your keys
In the dashboard open Stores, choose your store and find API keys: a public key (pk_…) and a secret key (sk_…). Showing the secret key needs a code from your authenticator app (see below). Keep it on your server.
2. Create an invoice
POST /api/v1/invoices with the amount and your order id, save the invoice id with your order, then send the customer to invoice_url.
3. Handle the webhook
Save a webhook URL and get its webhook secret on the Webhooks page. When invoice.paid arrives with a valid signature, mark the order as paid.
Base URL
https://merchant.arionpay.com/api/v1
JSON in, JSON out. Errors look like { "error": "message", "code": "…" }; code is present only for some errors.
Before your first request
Your keys are protected: showing a secret, or changing where webhooks go, needs a fresh code from an authenticator app (Google Authenticator, Authy, 1Password and similar), and each of these actions is recorded in your audit log and emailed to you. Do this once:
Sign up and confirm your email
Open the link we email you. You can log in only after that. Your first store and its keys are created for you.
Turn on two-factor login
Settings > Security, with an authenticator app (we email you a code first to confirm it is you). Email codes are not offered as the second factor.
Copy the API keys
Stores > your store > API keys. The public key is shown; showing or copying the secret key asks for an app code.
Set the webhook URL and secret
Webhooks page: save your https URL (asks for an app code), then press Replace secret. The new whsec_… secret is shown once, so copy it to your server.
Test
Create test invoices and simulate payments. No wallet and no fee balance are needed.
Go live
Connect a wallet to the store (asks for an app code) and leave out "test": true.
A new secret key (Stores > Regenerate) or webhook secret stops the old one at once, so update your server straight after.
Sign every request
Requests to your invoices are signed with your secret key. There is no Bearer token. Send these three headers, and Content-Type: application/json on POST requests:
| Header | Value |
|---|---|
| x-api-key | Your store's public key, pk_… |
| x-timestamp | The current Unix time in seconds. Requests more than 5 minutes off are rejected with 401, so keep your server clock in sync. Each signed request is accepted once: to retry, sign again with a new timestamp. |
| x-signature | Lowercase hex HMAC-SHA256 of the string to sign, keyed with your secret key sk_… |
String to sign
POST: <timestamp>.<raw request body>
1730000000.{"amount":"49.00","currency":"USD","test":true}
GET: <timestamp>.GET <path and query>
1730000000.GET /api/v1/invoices/6730f1c2a9e4b5d7c8f01234
The timestamp is the same string you send in x-timestamp (whole seconds, not milliseconds). For GET, sign the path and the query string exactly as they appear in the request, for example /api/v1/invoices/<id>?a=1, without the host.
- Sign the exact bytes you send. If you sign one JSON string and then let your HTTP library encode the object again (with different spacing or key order), the signature will not match.
- Send Content-Type: application/json on every POST. Without it the body is not read, and the request fails as "Invalid signature".
- Each signed request is accepted once. Two identical requests made in the same second have the same signature, so the second one is refused (401, "already used"). This also applies to two POSTs with the same body to different paths, for example the same scenario simulated on two invoices. When you retry or poll, wait until the next second and sign again.
Create an invoice
This creates a test invoice. Remove "test": true to take real payments (that needs a confirmed email and a connected wallet). All fields are listed in the .
// Node.js 18 or newer (built-in fetch), no packages needed.
// Save as request.mjs and run: node request.mjs
import crypto from 'node:crypto';
const BASE_URL = 'https://merchant.arionpay.com';
const PUBLIC_KEY = process.env.ARIONPAY_PUBLIC_KEY; // pk_...
const SECRET_KEY = process.env.ARIONPAY_SECRET_KEY; // sk_...
const path = '/api/v1/invoices';
const body = JSON.stringify({
"amount": "49.00",
"currency": "USD",
"orderId": "order-1001",
"description": "Order #1001",
"successUrl": "https://shop.example.com/thanks",
"cancelUrl": "https://shop.example.com/cart",
"test": true
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
.createHmac('sha256', SECRET_KEY)
.update(`${timestamp}.${body}`)
.digest('hex');
const res = await fetch(BASE_URL + path, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': PUBLIC_KEY,
'x-timestamp': timestamp,
'x-signature': signature,
},
body, // send exactly the string you signed
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.error}`);
console.log('Invoice', data.id, '- send the customer to', data.invoice_url);Response (201)
{
"status": "success",
"id": "6730f1c2a9e4b5d7c8f01234",
"invoice_url": "https://merchant.arionpay.com/pay/6730f1c2a9e4b5d7c8f01234",
"data": {
"id": "6730f1c2a9e4b5d7c8f01234",
"invoice_url": "https://merchant.arionpay.com/pay/6730f1c2a9e4b5d7c8f01234",
"amount_fiat": 49,
"currency": "USD",
"status": "new",
"asset": "USDT_TRC20",
"address": "TEST-MODE-DO-NOT-SEND-FUNDS",
"amount_crypto": "49",
"expires_at": "2026-11-05T12:30:00.000Z",
"order_id": "order-1001"
}
}Save id with your order and send the customer to invoice_url. The checkout page shows the coins your store accepts. When the customer picks one, the invoice gets its address (your wallet's main address, with a unique amount for this invoice), and the price is fixed in that coin until the invoice expires (default 30 minutes, and at least 15 minutes after the coin is chosen).
If the request times out and you do not know whether it worked, send it again with the same idempotencyKey (signed again, at least one second later): you get the first invoice back instead of a second one.
Check an invoice
Webhooks tell you when something changes. To look an invoice up yourself, sign <timestamp>.GET <path> instead of a body:
// Node.js 18 or newer (built-in fetch), no packages needed.
// Save as request.mjs and run: node request.mjs
import crypto from 'node:crypto';
const BASE_URL = 'https://merchant.arionpay.com';
const PUBLIC_KEY = process.env.ARIONPAY_PUBLIC_KEY; // pk_...
const SECRET_KEY = process.env.ARIONPAY_SECRET_KEY; // sk_...
const path = '/api/v1/invoices/INVOICE_ID'; // replace INVOICE_ID
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
.createHmac('sha256', SECRET_KEY)
.update(`${timestamp}.GET ${path}`)
.digest('hex');
const res = await fetch(BASE_URL + path, {
headers: { 'x-api-key': PUBLIC_KEY, 'x-timestamp': timestamp, 'x-signature': signature },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.error}`);
console.log(data);Test without real money
Add "test": true when you create an invoice. Test invoices never get a real address (the checkout shows TEST-MODE-DO-NOT-SEND-FUNDS), carry no fee, and send real, signed webhooks with "livemode": false and "test": true in the invoice. Test mode needs no wallet and no fee balance.
To pay a test invoice from your server, it needs a coin first: pass "asset": "USDT_TRC20" (or any asset code) when you create it, or pick a coin on the test checkout page. The invoice from the example above has no coin, so the simulate call would answer 400. Create one like this:
// Node.js 18 or newer (built-in fetch), no packages needed.
// Save as request.mjs and run: node request.mjs
import crypto from 'node:crypto';
const BASE_URL = 'https://merchant.arionpay.com';
const PUBLIC_KEY = process.env.ARIONPAY_PUBLIC_KEY; // pk_...
const SECRET_KEY = process.env.ARIONPAY_SECRET_KEY; // sk_...
const path = '/api/v1/invoices';
const body = JSON.stringify({
"amount": "49.00",
"currency": "USD",
"orderId": "test-order-1001",
"asset": "USDT_TRC20",
"test": true
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
.createHmac('sha256', SECRET_KEY)
.update(`${timestamp}.${body}`)
.digest('hex');
const res = await fetch(BASE_URL + path, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': PUBLIC_KEY,
'x-timestamp': timestamp,
'x-signature': signature,
},
body, // send exactly the string you signed
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.error}`);
console.log('Invoice', data.id, '- send the customer to', data.invoice_url);Step 1: a test invoice with its coin chosen. Copy the id it prints.
Then call the simulate endpoint with that id, signed like any other POST:
// Node.js 18 or newer (built-in fetch), no packages needed.
// Save as request.mjs and run: node request.mjs
import crypto from 'node:crypto';
const BASE_URL = 'https://merchant.arionpay.com';
const PUBLIC_KEY = process.env.ARIONPAY_PUBLIC_KEY; // pk_...
const SECRET_KEY = process.env.ARIONPAY_SECRET_KEY; // sk_...
const path = '/api/v1/invoices/INVOICE_ID/simulate'; // replace INVOICE_ID
const body = JSON.stringify({
"scenario": "exact"
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
.createHmac('sha256', SECRET_KEY)
.update(`${timestamp}.${body}`)
.digest('hex');
const res = await fetch(BASE_URL + path, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': PUBLIC_KEY,
'x-timestamp': timestamp,
'x-signature': signature,
},
body, // send exactly the string you signed
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.error}`);
console.log(data);Step 2: replace INVOICE_ID. Webhooks follow within a few seconds.
Anyone who opens a test invoice's checkout page can pay it there with pretend money. Remove "test": true before you go live, and never ship an order for a test invoice: act only on webhooks, or GET responses, with "livemode": true.
| scenario | What happens | Result |
|---|---|---|
| detected | The full amount is seen on the network but not yet confirmed. | pending (webhook invoice.pending) |
| confirm | Confirms everything seen so far. Run it after "detected". | paid if the amount was enough |
| exact | The exact amount arrives with all confirmations. | paid |
| underpaid_1pct | 1% less than the amount due arrives. | paid, flag underpaidWithinTolerance (inside the default 1% tolerance). With a store tolerance below 1%: nothing changes and the response has "radar": true. |
| underpaid_5pct | 5% less than the amount due arrives. | Fixed address (the default): outside the tolerance, so nothing changes and the response has "radar": true. Older invoices with their own address: paid_partial. |
| overpaid | 2% more than the amount due arrives. | More than the default 1% tolerance, so it is not paid by itself. Fixed address (the default): nothing changes and the response has "radar": true. Invoices with their own address: status pending and the event invoice.needs_review. With a store tolerance of 2% or more: paid, flag overpaid. |
| partial_half | Half the amount arrives. | Fixed address (the default): nothing changes and the response has "radar": true. Older invoices with their own address: paid_partial. |
| late | The invoice is moved past its expiry, then the full amount arrives. | paid, flag late |
Statuses, flags and payment rules
| status | Meaning |
|---|---|
| new | Created. Nothing received yet. |
| pending | Enough was seen on the network; waiting for confirmations. |
| paid_partial | Some money arrived, but less than the amount due. The customer can send the rest to the same address. |
| paid | Paid in full and confirmed. Ship the order. |
| expired | Not paid in time. Not always final: a payment that arrives within 30 minutes after expiry turns it into paid (flag late). After that the invoice is no longer watched; a payment the customer reports by its transaction ID waits for the store owner's review, as does a late one in a coin whose price has fallen since. |
| cancelled | Cancelled by the store owner in the dashboard (only possible while nothing was received). No webhook is sent for it. |
| claim_pending | Unpaid (new or expired), and the customer has reported a payment ("I already paid") that you have not answered yet. Nothing is confirmed on the blockchain. Do not ship. |
| rejected | Unpaid (new or expired), and you rejected the customer's payment report. |
| Flag | Meaning |
|---|---|
| underpaidWithinTolerance | Paid, but a little short, within your store's tolerance (default 1%, you can set 0 to 5%). |
| overpaid | Paid, and the customer sent more than the amount due. |
| late | Paid after the invoice expired. Automatic within 30 minutes of expiry, which is how long an expired invoice is still watched (a store can make it shorter). |
| needsReview | Needs your decision, for example a possible double payment, or a late payment in a coin whose price has fallen. reviewReason says why. |
- Payments go to the wallet's main address and each invoice has a unique amount. That exact amount is confirmed automatically.
- An amount within the store's payment tolerance (1% by default, 0 to 5% per store, less or more) is confirmed automatically too, when it arrived while the invoice was open and no other unpaid invoice has a similar amount. The invoice gets the flag underpaidWithinTolerance or overpaid, and is tagged as paid with Radar.
- Any other amount is shown to the store owner by Payment Radar. If they accept it, the invoice is paid and tagged as paid with Radar.
- Older invoices with their own address follow the older rules: up to 1% short counts as paid (0 to 5% per store), paying more sets the overpaid flag, and several transactions are added up.
- An expired invoice is watched for 30 more minutes. A payment that arrives in that time counts as paid and late (a store can make this time shorter). Later the invoice is closed; a payment the customer reports by its transaction ID waits for the store owner's review. So does a late one in a coin whose price has fallen since, and one that is more than the store's tolerance above the invoice amount on an invoice with its own address.
- If an invoice is paid twice, it is marked for your review.
- An invoice is paid only after the network confirmations below. There is no zero-confirmation acceptance.
- A customer can report a payment on the checkout page ("I already paid"). Until you accept or reject it in the dashboard, an unpaid invoice shows claim_pending. Accepting it marks the invoice paid by hand (invoice.paid with manual: true).
- The customer can switch coin, or reopen an expired invoice that received nothing. Each time the invoice gets a new quote (a new address or a new unique amount) and a new price, so invoice.pending, invoice.partial or invoice.expired can be sent again for the same invoice. invoice.paid is sent once.
| Network | Asset codes | Confirmations | Usually paid in |
|---|---|---|---|
| Bitcoin | BTC | 1 | about 10 minutes |
| Ethereum | ETH, USDT_ERC20, USDC_ERC20 | 2 | under 1 minute |
| BNB Smart Chain | BNB, USDT_BEP20, USDC_BEP20 | 2 | a few seconds |
| Polygon | POL, USDT_POLYGON, USDC_POLYGON | 2 | a few seconds |
| TRON | TRX, USDT_TRC20 | 19 | about 1 minute |
| Litecoin | LTC | 2 | about 5 minutes |
| Dogecoin | DOGE | 20 | about 20 minutes |
| Bitcoin Cash | BCH | 6 | about 1 hour |
| Dash | DASH | 6 | about 15 minutes |
Estimates from each network’s average block time. ArionPay sees most payments within seconds; a busy network or a low network fee can take longer.
16 coins and tokens on 9 networks today.More networks Coming soon
Fees and errors
The fee is 0.5% of each payment received, taken from your prepaid fee balance; customers' payments reach your wallet in full. There is no monthly or setup fee and no fee on test invoices. New accounts start with $20 of fee credit. When it is used up, creating a real invoice returns 402 until you top up (from $5, in crypto).
| HTTP | Meaning |
|---|---|
| 400 | Invalid input: for example a missing amount, an amount below 0.10, an unsupported currency or coin, a malformed invoice id or invalid JSON. code no_payment_method: the store has no wallet for real invoices (or none of the requested coins can be paid to it). code unknown_asset: a misspelt coin code in allowedAssets. |
| 401 | Missing or unknown key, wrong signature, no x-timestamp or one more than 5 minutes off, or a signed request that was already used. No code field. A body sent without Content-Type: application/json is not read, so it also fails as "Invalid signature". |
| 402 | code balance_empty: your fee credit is used up. Top up your fee balance (from $5, in crypto) to create real invoices again. |
| 403 | code email_unverified: the account's email is not confirmed. Without a code: the store or account is disabled, or storeId does not match the key. |
| 404 | No such invoice for this store (or no such path). |
| 409 | code idempotency_key_reused: the key was already used with a different amount, currency or orderId. Without a code: simulating a test invoice that is already paid, or the invoice was being changed at that moment (sign again and retry). |
| 429 | code rate_limited. 120 requests per minute from one IP address to each endpoint (a Retry-After header says when to try again), and 300 signed requests per minute per store in total. POST /api/v1/webhooks/test: 10 per minute. |
| 500 / 503 | A problem on our side, for example a network temporarily unavailable while assigning an address (503). Retry later, signed again. |
Already connected to the old ArionPay API?
Accounts and keys from the old system were not carried over: create a new account, turn on an authenticator app, connect a wallet and use the new store's keys. Shop code written for the old API, which calls https://api.arionpay.com/api/v1 and signs only the body (no x-timestamp), works when you turn on Stores > your store > Settings > "Old ArionPay (v1) integration compatibility" (it asks for an authenticator code). The old field names chain (the coin to pre-select) and returnUrl (= successUrl) are still accepted.
That switch is less safe: an old-style signature has no time limit, and webhooks are signed with your API secret. Move your code to the current scheme on this page (https://merchant.arionpay.com/api/v1, x-timestamp, ArionPay-Signature), then turn the switch off.