CryptoPayr Docs
Dashboard Get API key

REST API · v1

Accept crypto with a few API calls

Create a payment from your backend, send your customer to the hosted checkout, and get a signed webhook when it's paid. Plain REST, JSON in and out. Coins never touch your servers.

Base URL https://cryptopayr.com

How a payment works

  1. Create the payment on your server with POST /api/v1/payment/create.
  2. Redirect your customer to the checkout_url you get back. They pick a coin and pay.
  3. Fulfil the order when the COMPLETED webhook arrives.

The customer can pick any supported coin and network. Set pay_currency on a payment (or a payment link) to pin one coin and skip the picker. Prefer no code? Create a payment link in the dashboard and share the URL.

Authentication

Send your key as a Bearer token in the Authorization header. Find your keys under Dashboard → Developers. Market-data endpoints (rates, convert) and the payment lookup need no key.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
KeyUsed for
sk_live_…Secret key Every live endpoint: payments, refunds, balance, lists and lookups. Also signs your webhooks.
sk_test_…Test key Test mode. Accepted by payment/create, payment/lookup and payment/test-complete. Never touches your balance.
wk_live_…Withdrawal key Endpoints that move money out: payout/create, transfer/create and the payout-link writes. Shown once when you create it.
Keep your keys on your server. Never put them in client-side code, a mobile app or a public repository.

OpenAPI & Postman

The whole API, including the public exchange endpoints, is described by an OpenAPI 3.1 spec. Import it into a client generator, Postman or any API explorer.

SDKs

Official libraries for PHP, Node.js and Python wrap payments, payment links, payouts, transfers, refunds, balance, transactions, market data and webhook verification. None has third-party dependencies. Every example on this page has an SDK tab; pick a language once and every example follows.

Download the zip from the SDK's page, unzip it next to your code and install it from that folder:

// Unzip cryptopayr-php-sdk.zip next to your code (works with or without Composer)
require __DIR__ . '/cryptopayr-php-sdk/autoload.php';

$cp = new \CryptoPayr\Client([
    'api_key'        => 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx',
    'withdrawal_key' => 'wk_live_xxxxxxxxxxxxxxxxxxxxxxxx', // only for payouts/transfers
]);
// npm install ./cryptopayr-node-sdk   (the unzipped download)
const CryptoPayr = require('cryptopayr');

const cp = new CryptoPayr({
  apiKey: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx',
  withdrawalKey: 'wk_live_xxxxxxxxxxxxxxxxxxxxxxxx', // only for payouts/transfers
});
# pip install ./cryptopayr-python-sdk   (the unzipped download)
from cryptopayr import Client

cp = Client(
    api_key="sk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    withdrawal_key="wk_live_xxxxxxxxxxxxxxxxxxxxxxxx",  # only for payouts/transfers
)

Each call returns the data object of the response and throws on any error, with the HTTP status as the error code:

use CryptoPayr\ApiException;

try {
    $cp->payments->cancel($tid);
} catch (ApiException $e) {
    $e->getCode();     // HTTP status (0 = network error or missing key)
    $e->getMessage();  // the API's "error" text
}
const { ApiError } = require('cryptopayr');

try {
  await cp.payments.cancel(tid);
} catch (e) {
  if (e instanceof ApiError) {
    e.code;    // HTTP status (0 = network error, timeout or missing key)
    e.message; // the API's "error" text
  }
}
from cryptopayr import ApiError

try:
    cp.payments.cancel(tid)
except ApiError as e:
    e.code     # HTTP status (0 = network error or missing key)
    e.message  # the API's "error" text
The SDKs don't wrap payout links, platform sub-accounts, payment/address, payment/methods or payment/test-complete yet. Call those with the low-level request() method every SDK has, as the payout link example shows.

Idempotency

Send an Idempotency-Key header (any unique string up to 200 characters, e.g. your order id or a UUID) on calls that create something. If the same key comes in again within 24 hours, we return the first result instead of doing the work twice, with an Idempotency-Replayed: true header.

EndpointNotes
POST /payment/createRetry a timed-out create without opening a second payment. Test-mode keys are kept apart from live ones.
POST /refund/createOne refund per key.
POST /payout/createStrongly recommended. A replay of a payout whose outcome was unclear returns the same 502 and never sends again.
POST /transfer/createOnly a completed transfer is remembered; a failed one can be retried with the same key.
POST /payout-link/createA second request while the first is still running gets 409. A replay returns url: null, because the link is shown once.

Keys are kept separately per endpoint, so the same key on payment/create and refund/create are two different keys. A second request with a key whose first request is still running gets 409 instead of doing the work twice; retry it a moment later to get the stored result. A request that failed without changing anything (a 422, say) frees its key, so you can fix the body and send it again with the same key.

The request body isn't compared: a replay returns the first result even if the body changed. Use a new key when you mean a new operation.

Pagination

List endpoints return 50 rows per page, newest first. Pass page (1-based) and read the envelope inside data:

{
  "status": "success",
  "data": {
    "page": 1,
    "per_page": 50,
    "total": 128,
    "total_pages": 3,
    "has_more": true,
    "data": [ … ]
  }
}

Keep requesting page + 1 while has_more is true. A page past the end returns an empty list, not an error.

EndpointFilters
GET /transactionsstatus, sort (date or status), role (platforms)
GET /payoutsstatus: PENDING, PROCESSING, COMPLETED, REJECTED
GET /refundsstatus: REQUESTED, PROCESSING, COMPLETED, REJECTED, CANCELLED
GET /transfersdirection: in or out
GET /payout-linksstatus: ACTIVE, CLAIMING, PROCESSING, HELD, COMPLETED, CANCELLED, EXPIRED
GET /accountsPlatforms only. No filters.

GET /payment-links (your newest 50) and GET /payout-addresses (all of them) are not paginated and return { "data": [ … ] }.

Test mode

Build and test your integration without moving money. Your test key (sk_test_…, under Dashboard → Developers) creates test payments that never touch your balance, stats or reports. Test payment ids start with tt_.

POST/api/v1/payment/createTest key

Same request as live. Returns a tt_… id and a test checkout_url.

GET/api/v1/payment/lookup?tid={tt_…}No key

Works for test payments too; the answer carries "test": true.

POST/api/v1/payment/test-completeTest key

Moves a test payment to COMPLETED (default), EXPIRED, CANCELLED, UNDERPAID or REFUNDED and sends the webhook. With COMPLETED you can add underpaid: true and amount_paid; with REFUNDED, refund_amount (USD) and refund_id.

# 1) create a test payment with your sk_test_ key
curl -X POST https://cryptopayr.com/api/v1/payment/create \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount":19.99,"currency":"USD","webhook_url":"https://shop.example/hook"}'

# 2) drive it to the event you want to test
curl -X POST https://cryptopayr.com/api/v1/payment/test-complete \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"tid":"tt_…","status":"COMPLETED"}'
$test = new \CryptoPayr\Client(['api_key' => 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxx']);

$p = $test->payments->create([
    'amount' => 19.99, 'currency' => 'USD', 'webhook_url' => 'https://shop.example/hook',
]);
$test->request('POST', 'api/v1/payment/test-complete', ['tid' => $p['tid'], 'status' => 'COMPLETED']);
const test = new CryptoPayr({ apiKey: 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' });

const p = await test.payments.create({
  amount: 19.99, currency: 'USD', webhook_url: 'https://shop.example/hook',
});
await test.request('POST', 'api/v1/payment/test-complete', { tid: p.tid, status: 'COMPLETED' });
test = Client(api_key="sk_test_xxxxxxxxxxxxxxxxxxxxxxxx")

p = test.payments.create({
    "amount": 19.99, "currency": "USD", "webhook_url": "https://shop.example/hook",
})
test.request("POST", "api/v1/payment/test-complete", {"tid": p["tid"], "status": "COMPLETED"})

The response of test-complete includes webhook_delivered, webhook_http and the exact webhook_payload we sent. Test webhooks are signed with your test key and carry "test": true plus an X-CryptoPayr-Test: true header; otherwise they have the live shape, including amount as a string and settlement, amount_paid and underpaid on a paid payment. To rehearse a short payment exactly as live sends it, use "status": "COMPLETED", "underpaid": true (optionally amount_paid; default 90% of the order). Every other endpoint refuses the test key with 401.

Try it

Run a test payment from this page. It uses your test key only and never touches real money.

Responses appear here.

Fees

Crypto processing fees are a percentage that starts at 1% and drops automatically with your volume, plus a flat $0.10 per payment — billed only on successful payments. No setup or monthly fees. Full pricing: cryptopayr.com/pricing.

Rolling 30-day volumeFee
$0 – $4,9991% + $0.10
$5,000 – $14,9990.5% + $0.10
$15,000+0.1% + $0.10

Added to the processing fee when they apply:

FeeRateWhen
White label+1%The deposit address was fetched with POST /api/v1/payment/address (your own checkout), or the buyer paid on your custom domain.
Conversion+1%The payment is converted and credited to your USD balance (settlement_mode: convert). Not charged with direct settlement.
Refund1% of the refundDeducted from what the customer receives. Your balance is debited the refund amount; the REFUNDED webhook carries refund_fee and refund_net.

Accounts opened before 1 November 2026 keep their previous schedule (2% / 1.5% from $1,000 / 1% from $5,000, no add-ons) until we move them. GET /api/v1/account returns your fee_percent, fixed_fee, fee_schedule (current or legacy) and the add-ons that apply in fee_addons. Your current rate is also shown in the dashboard, and every completed payment has a PDF receipt with the fee itemised. By default the merchant absorbs the fee; set buyer_pays_fees: 1 to add it on top of the amount your customer pays.

Create a payment

POST/api/v1/payment/createSecret key

Creates a charge and returns a hosted checkout_url to send your customer to.

FieldTypeDescription
amountnumberRequired Amount in the fiat currency.
currencystringRequired 3-letter fiat code, e.g. USD.
webhook_urlstringPer-payment endpoint we POST the signed confirmation to. Overrides your account default for this payment; omit to use the default.
success_urlstringRedirect after a successful payment.
cancel_urlstringRedirect if the customer cancels.
pay_currencystringOptional Pin the pay-in coin (e.g. USDT) to skip the picker.
pay_networkstringOptional Network for the pinned coin (e.g. TRON).
allowed_coinsarrayOptional Only these coins and networks are shown on the checkout, e.g. ["USDT:TRON", "USDT:BSC", "BTC", "ETH", "LTC"]. A coin on its own means every network of it. See Limit the coins.
buyer_pays_fees0 / 1Add the processing fee on top of the amount.
metadatastringYour own reference (≤ 255 chars), echoed back in webhooks.
on_behalf_ofstringPlatforms A client's account ID (usr_…) to credit instead of yourself. Requires a platform account.
platform_fee_percentnumberPlatforms Commission percent of the order value (0–50). Deducted from the client's net.
platform_fee_fixednumberPlatforms Fixed commission in USD on top of the percent (0–10000).

Marketplaces. If your account is a platform account, pass on_behalf_of with a client's account ID (they share their usr_… id with you) to create the charge on their account, authenticated with your API key. Your commission (platform_fee_percent of the order value plus platform_fee_fixed) is deducted from the client's net when the payment completes and credited to your balance — capped at the client's net so it can never go negative. List the Orders you've created with GET /api/v1/transactions?role=platform, and register a platform webhook in your platform settings to receive a signed order.completed event (with the commission_usd) for each one. Ordinary merchants can ignore these fields.

Send an Idempotency-Key header (any unique string, e.g. a UUID) to make retries safe — replaying the same key for 24h returns the original payment instead of creating a duplicate. Replays come back with an Idempotency-Replayed: true header.

curl -X POST https://cryptopayr.com/api/v1/payment/create \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_4815" \
  -d '{
    "amount": 149.00,
    "currency": "EUR",
    "webhook_url": "https://shop.example/hook",
    "success_url": "https://shop.example/thanks",
    "metadata": "order_4815"
  }'
$payment = $cp->payments->create([
    'amount'      => 149.00,
    'currency'    => 'EUR',
    'webhook_url' => 'https://shop.example/hook',
    'success_url' => 'https://shop.example/thanks',
    'metadata'    => 'order_4815',
], 'order_4815'); // Idempotency-Key (optional)

header('Location: ' . $payment['checkout_url']);
const payment = await cp.payments.create(
  {
    amount: 149.0,
    currency: 'EUR',
    webhook_url: 'https://shop.example/hook',
    success_url: 'https://shop.example/thanks',
    metadata: 'order_4815',
  },
  'order_4815' // Idempotency-Key (optional)
);

res.redirect(payment.checkout_url);
payment = cp.payments.create(
    {
        "amount": 149.00,
        "currency": "EUR",
        "webhook_url": "https://shop.example/hook",
        "success_url": "https://shop.example/thanks",
        "metadata": "order_4815",
    },
    idempotency_key="order_4815",  # optional
)

checkout_url = payment["checkout_url"]

Response

{
  "status": "success",
  "message": "Payment created",
  "data": {
    "tid": "8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1",
    "status": "CREATED",
    "amount": 149.00,
    "currency": "EUR",
    "checkout_url": "https://cryptopayr.com/payment/8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1"
  }
}

Limit the coins at checkout

By default buyers can pick any coin we support. To offer only some, either:

  • For every payment: in the dashboard go to Settings → Payments → Coins at checkout, choose Only the coins I pick and tick the coins and networks you want. This applies to API payments, payment links, invoices and the POS.
  • For one payment: send allowed_coins with POST /api/v1/payment/create. It replaces your dashboard choice for that payment.
curl -X POST https://cryptopayr.com/api/v1/payment/create \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "allowed_coins": ["USDT:TRON", "USDT:BSC", "BTC", "ETH", "LTC"]
  }'

Write each entry as COIN (every network of that coin) or COIN:NETWORK. Network codes are the ones GET /api/v1/payment/methods returns (TRON, BSC, ETH, POLYGON, SOL, …); the usual names work too: TRC20, BEP20, ERC20. A comma-separated string ("USDT:TRON,BTC") is accepted as well. An entry we don't offer is refused with 422, so a typo shows up when you create the payment, not on your customer's screen. The response echoes the list as allowed_coins.

The buyer still picks on our hosted checkout. They only see your coins, and a deposit can't be opened for anything else (POST /api/v1/payment/address refuses it too). pay_currency still pins one coin and skips the picker. Card and other payment options keep their own settings.

Building your own picker? Call GET /api/v1/payment/methods with your API key and it returns only the coins your checkout allows (add ?tid= for one payment's list).

Look up a payment

GET/api/v1/payment/lookup?tid={tid}No key

Public, read-only status check. Used for reconciliation and by the hosted checkout to detect confirmation.

curl https://cryptopayr.com/api/v1/payment/lookup?tid=8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1
$p = $cp->payments->lookup($tid);
echo $p['status']; // CREATED | PENDING | COMPLETED | EXPIRED | CANCELLED
const p = await cp.payments.lookup(tid);
console.log(p.status);
p = cp.payments.lookup(tid)
print(p["status"])

Response

{
  "status": "success",
  "data": {
    "tid": "8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1",
    "status": "COMPLETED",
    "amount": "149.0000",
    "amount_usd": "172.3200",
    "currency": "EUR",
    "created_at": "2026-06-06 12:00:00",
    "expires_at": "2026-06-06T13:00:00+01:00",
    "expires_in": 3214,
    "coin": "USDT",
    "crypto_amount": 172.32,
    "received": 172.32,
    "remaining": 0,
    "partial": 0
  }
}

The coin, crypto_amount, received, remaining and partial fields appear once the customer has selected a coin on the hosted checkout — handy for showing live payment progress. A completed payment also carries amount_paid and underpaid, as in the webhook. expires_in is the seconds left before the invoice expires.

List transactions

GET/api/v1/transactionsSecret key

Returns your transactions, newest first, 50 per page. Authenticate with your secret API key.

QueryTypeNotes
pageinteger1-based page number. Default 1.
statusstringOptional Filter: CREATED, PENDING, COMPLETED, EXPIRED or CANCELLED.
sortstringdate (default, newest first) or status (grouped by status).
rolestringPlatforms merchant (default — your own received payments) or platform (the Orders you created on behalf of clients). The platform listing adds on_behalf_of, platform_fee_percent, platform_fee_fixed and commission_usd (the credited commission, or null until the Order completes) to each row.
curl "https://cryptopayr.com/api/v1/transactions?page=1&status=COMPLETED" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
$page = $cp->account->transactions(['page' => 1, 'status' => 'COMPLETED']);
foreach ($page['data'] as $tx) {
    echo $tx['tid'], ' ', $tx['amount'], ' ', $tx['currency'], PHP_EOL;
}
const page = await cp.account.transactions({ page: 1, status: 'COMPLETED' });
for (const tx of page.data) console.log(tx.tid, tx.amount, tx.currency);
page = cp.account.transactions({"page": 1, "status": "COMPLETED"})
for tx in page["data"]:
    print(tx["tid"], tx["amount"], tx["currency"])

Response

{
  "status": "success",
  "data": {
    "page": 1,
    "per_page": 50,
    "total": 128,
    "total_pages": 3,
    "has_more": true,
    "data": [
      {
        "tid": "8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1",
        "status": "COMPLETED",
        "amount": 149.00,
        "currency": "EUR",
        "amount_usd": 172.32,
        "buyer_pays_fees": 0,
        "metadata": "order-1024",
        "created_at": "2026-06-06T12:00:00+01:00"
      }
    ]
  }
}

Cancel a payment

POST/api/v1/payment/cancelSecret key

Void an unpaid invoice early instead of waiting for it to expire. Body: { "tid": "…" }. Only CREATED/PENDING payments can be cancelled — a COMPLETED one returns 409.

curl -X POST https://cryptopayr.com/api/v1/payment/cancel \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"tid":"8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1"}'
$r = $cp->payments->cancel($tid); // $r['status'] === 'CANCELLED'
const r = await cp.payments.cancel(tid);
r = cp.payments.cancel(tid)

Response

{ "status": "success", "data": { "tid": "8f14…", "status": "CANCELLED" } }

List coins and networks

GET/api/v1/payment/methodsNo key

The coins and networks buyers can pay with. Public; send your secret key to get only the coins your checkout allows (your Coins at checkout setting), and add ?tid= for one payment's list. An unknown key is ignored, never refused.

curl "https://cryptopayr.com/api/v1/payment/methods" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "status": "success",
  "message": "OK",
  "data": {
    "coins": [
      { "ticker": "BTC", "name": "Bitcoin", "networks": [{ "network": "BTC", "label": "Bitcoin" }], "payout": true },
      { "ticker": "USDT", "name": "Tether", "networks": [{ "network": "TRON", "label": "TRC-20" }], "payout": false }
    ],
    "count": 2,
    "payout_coins": ["BTC"]
  }
}

payout tells you whether you can also withdraw in that coin from your USD balance. allowed_coins is added when a list was applied.

Get a deposit address (your own checkout)

POST/api/v1/payment/addressSecret key

Build your own payment page instead of sending buyers to ours: create the payment, then fetch the deposit address for the coin the buyer picked and show it yourself. Settlement and the webhook are the same as with the hosted checkout.

FieldTypeNotes
tidstringRequired A payment you created.
coinstringRequired Ticker from payment/methods, e.g. BTC.
networkstringOptional e.g. TRON; TRC20, BEP20 and ERC20 work too. Default: the coin's first network.
curl -X POST https://cryptopayr.com/api/v1/payment/address \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"tid":"8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1","coin":"USDT","network":"TRON"}'

Response

{
  "status": "success",
  "message": "OK",
  "data": {
    "tid": "8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1",
    "status": "PENDING",
    "coin": "USDT",
    "coin_name": "Tether",
    "network": "TRON",
    "network_label": "TRC-20",
    "address": "TQx…",
    "amount": "172.32",
    "amount_fiat": 149,
    "currency": "EUR",
    "qr": "TQx…",
    "created_at": "2026-11-10 12:00:00",
    "expires_at": "2026-11-10T13:00:00+00:00",
    "expires_in": 3540
  }
}

Calling it again with the same coin and network returns the same address. A different coin gives a new address; a deposit to the old one still settles. Poll payment/lookup for progress and wait for the COMPLETED webhook.

On the current pricing a deposit address fetched this way adds the +1% white-label fee (see Fees). Errors: 409 when the payment is already completed, expired or cancelled; 422 for a coin the payment doesn't allow; 502/503 when that coin can't take payments right now (try another).

Re-check a payment now

POST/api/v1/payment/recheckNo key

Asks us to look for the buyer's deposit right away instead of waiting for the network notice. It's the "Check for payment" button on the hosted checkout. Public, limited to one real check per payment every 5 minutes.

curl -X POST https://cryptopayr.com/api/v1/payment/recheck \
  -H "Content-Type: application/json" \
  -d '{"tid":"8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1"}'

Response

{ "status": "success", "message": "PENDING", "data": { "status": "PENDING", "settled": false, "message": "No payment detected yet." } }

Read data.settled and data.status. Within the 5-minute window you get "message": "COOLDOWN" with retry_after in seconds. A part payment adds partial, received, remaining and coin. Form fields, a JSON body and ?tid= all work.

Pay with a Rewarble voucher (your own checkout)

POST/api/v1/payment/rewarbleSecret key

Take Rewarble vouchers on your own page, under your own brand: your server sends us the payment, the buyer's voucher code and their email, and we redeem it. The voucher's value, less the voucher fee, comes off the payment. Needs Pay by card on in Settings → Payments, and your live key.

FieldTypeNotes
tidstringRequired A payment you created, still open.
codestringRequired The voucher code as the buyer typed it.
emailstringRequired The buyer's email. If the voucher is worth more than the payment, the rest is kept as credit for this email.
customer_ipstringOptional The buyer's IP. Send it, so one buyer can't use up your account's attempts.
curl -X POST https://cryptopayr.com/api/v1/payment/rewarble \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"tid":"8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1","code":"ABCD-1234-EFGH-5678","email":"[email protected]","customer_ip":"203.0.113.7"}'

Response

{
  "status": "success",
  "message": "COMPLETED",
  "data": {
    "tid": "8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1",
    "status": "COMPLETED",
    "result": "COMPLETED",
    "replay": false,
    "voucher": { "credited_usd": 52.10, "fee_usd": 4.50, "applied_usd": 49.00, "leftover_usd": 3.10 },
    "amount_due_usd": 0,
    "completed": true
  }
}

COMPLETED: the payment is paid and the usual COMPLETED webhook follows. PARTIAL: the voucher covered part of it, amount_due_usd is left; take another voucher, or fetch a new deposit address for the rest (an address fetched before is for the old amount). 202 with REVIEW: the voucher was taken and our team checks it before it counts. Sending the same code again for the same payment and email gives back the first answer with "replay": true; an Idempotency-Key works too.

Errors carry a reason: invalid, expired, used, inactive, empty or email (422), closed (409, the payment isn't open), not_enabled (403), rate (429), service (503). unknown (502) means we couldn't confirm the voucher: don't ask the buyer to send it again, our team checks it and credits the buyer's email if it went through. Limits: 30 a minute and 60 an hour per account, 8 an hour per payment, 10 an hour per buyer email or IP; 15 refused codes in an hour pause voucher payments on your account for the rest of the hour.

Webhooks

When a payment is confirmed we POST a JSON event to your webhook_url — the endpoint you set per payment, or your account default from the dashboard settings. This is how you fulfil orders server-side; never rely on the buyer's browser reaching your success_url.

Request we send

POST /your/webhook  HTTP/1.1
Content-Type: application/json
X-CryptoPayr-Signature: 9f86d081884c7d659a2feaa0c55ad015a839f4f8...

{
  "tid": "8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1",
  "status": "COMPLETED",
  "amount": "149.0000",
  "currency": "EUR",
  "metadata": "order_4815",
  "timestamp": 1781049600
}

Payload fields

FieldTypeDescription
tidstringThe transaction id you got from create.
statusstringThe event — see the table below.
amountstringOrder amount in the fiat currency.
currencystring3-letter fiat code.
metadatastringYour own reference, echoed back verbatim.
timestampintegerUnix time the event was sent.
settlementstringconvert (credited as USD) or direct (credited in the coin paid). Present once a payment attempt exists.
settled_assetstringDirect settlement only — the coin your balance was credited in.
settled_networkstringDirect settlement only — the network the deposit arrived on.
received_cryptostringDirect settlement only — the cumulative on-chain amount received, as a decimal string.
amount_paidnumberWhat the buyer actually paid, in the order currency. Lower than amount only when you accept underpayments — deliver against this.
underpaidbooleantrue when the payment completed under your underpayment tolerance (at most 50%).
refund_idstringREFUNDED only — the refund this event is about. The same id POST /refund/create returned and GET /refunds lists.
refund_amountstringREFUNDED only — the USD amount refunded, as a decimal string. Not the same as amount, which stays the original order total.
refund_currencystringREFUNDED only — always USD, the currency refund_amount is stated in.
refund_settlementstringREFUNDED only — convert (refunded out of your USD balance) or direct (out of your coin balance).
refund_asset / refund_networkstringREFUNDED only — the coin and network the refund was sent on.
refund_asset_amountstringREFUNDED + direct settlement only — the coin amount that left your balance, as a decimal string.
refund_fee / refund_netstringREFUNDED only — the refund fee in USD (1% on the current pricing, 0.00 on the legacy schedule) and what the customer was sent before the network fee (refund_amount − refund_fee).
refund_asset_netstringREFUNDED + direct settlement only — the coin amount sent to the customer, after the refund fee.
Refunds can be partial, and there can be several against one payment. Every REFUNDED event for a payment repeats the same tid, amount and metadata — refund_id is what makes each one distinguishable, so key your refund bookkeeping on it rather than on tid. Note also that a refund does not change the payment's own status: GET /payment/lookup still reports COMPLETED afterwards. Reconcile against GET /refunds.

Events

statusWhen it fires
COMPLETEDPayment confirmed on-chain (or an in-tolerance underpayment was accepted). Funds are credited to your balance. This is the event to fulfil orders on.
PENDINGSent if you re-send an event while a transaction is still awaiting confirmations (e.g. via the dashboard's Resend webhook).
EXPIRED / CANCELLEDSent if you re-send an event for a transaction that expired or was cancelled. Use it to release a held order.
REFUNDEDA refund against this payment was sent on-chain. Fires automatically when the refund completes — reconcile your records and notify the customer if needed. Carries the refund_* fields above.
A successful payment delivers a single COMPLETED event automatically, and each completed refund a single REFUNDED one. The other statuses share the same signed format and are delivered when an event is re-sent from the dashboard — treat your handler as status-driven and idempotent (key on tid, and on refund_id for refunds) so it stays correct as more automatic events are added.

Testing your handler

Every event above can be delivered to your endpoint from test mode — including REFUNDED, so you never have to issue a live-money refund just to see its shape. Test payments are fully isolated: they never touch your balance, stats or reports. Take your sk_test_… key from Portal → Developers, create a payment with it exactly as you would with your live key, then drive it to the event you want:

curl -X POST https://cryptopayr.com/api/v1/payment/test-complete \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"tid":"tt_…","status":"REFUNDED","refund_amount":19.99}'

The response echoes the exact webhook_payload that was signed and sent. Pass the same refund_id twice to replay one refund event and prove your handler is idempotent. Test webhooks are signed with your test key and carry "test": true plus an X-CryptoPayr-Test: true header; the rest is the live shape. More in Test mode.

Verifying the signature

Every webhook carries an X-CryptoPayr-Signature header: an HMAC-SHA256 of the raw request body keyed with your secret API key (the same sk_live_… key you authenticate with). Compute the HMAC over the exact bytes you received and compare in constant time. Our official plugins verify the same way.

$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_CRYPTOPAYR_SIGNATURE'] ?? '';

$expected = hash_hmac('sha256', $body, $API_KEY);   // your sk_live_… key
if (!hash_equals($expected, $sig)) {
    http_response_code(400);
    exit;                                            // reject — not from CryptoPayr
}

$event = json_decode($body, true);
if ($event['status'] === 'COMPLETED') {
    // mark order $event['metadata'] as paid (idempotent on $event['tid'])
}
http_response_code(200);
use CryptoPayr\Webhook;
use CryptoPayr\ApiException;

try {
    $event = Webhook::parse(
        file_get_contents('php://input'),
        Webhook::signatureFromServer($_SERVER),
        'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx'
    );
} catch (ApiException $e) {
    http_response_code(400);
    exit;
}

if ($event['status'] === Webhook::STATUS_COMPLETED) {
    if (Webhook::isUnderpaid($event)) {
        $paid = Webhook::amountPaid($event); // hold the order, or deliver against $paid
    } else {
        // fulfil order $event['metadata']
    }
}
http_response_code(200);
const express = require('express');
const { Webhook } = require('cryptopayr');

const app = express();
app.post('/cryptopayr/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = Webhook.parse(req.body, Webhook.signatureFromHeaders(req.headers), 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx');
  } catch (e) {
    return res.sendStatus(400);
  }
  if (event.status === Webhook.STATUS_COMPLETED) {
    if (Webhook.isUnderpaid(event)) {
      const paid = Webhook.amountPaid(event); // hold the order, or deliver against paid
    } else {
      // fulfil order event.metadata
    }
  }
  res.sendStatus(200);
});
from flask import Flask, request
from cryptopayr import webhook, ApiError, STATUS_COMPLETED

app = Flask(__name__)

@app.post("/cryptopayr/webhook")
def cryptopayr_webhook():
    try:
        event = webhook.parse(
            request.get_data(),
            webhook.signature_from_headers(request.headers),
            "sk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
        )
    except ApiError:
        return "invalid signature", 400

    if event["status"] == STATUS_COMPLETED:
        if webhook.is_underpaid(event):
            paid = webhook.amount_paid(event)  # hold the order, or deliver against paid
        else:
            pass  # fulfil order event["metadata"]
    return "ok", 200
Always return 200 OK once you've stored the event. Delivery is a single attempt with a 15-second timeout and is not retried automatically — every attempt is logged, and a failed one can be re-sent by hand from the transaction page in your dashboard. So treat the webhook as a fast notification, not a guarantee: reconcile anything that matters against GET /payment/lookup and GET /refunds. Rotating your API key in the dashboard also rotates the webhook signing key.

Webhook event reference

Every webhook we send, in one place. All are a single POST with a JSON body, signed with X-CryptoPayr-Signature (HMAC-SHA256 of the raw body), sent once with no automatic retry, and listed under Dashboard → Webhooks.

EventSent toSigned withWhen
COMPLETEDThe payment's webhook_url, else your defaultSecret keyA payment is confirmed. Fulfil on this.
REFUNDEDSameSecret keyA refund was sent. Carries the refund_* fields.
PENDING, EXPIRED, CANCELLEDSameSecret keyOnly when you re-send a payment's webhook from the dashboard; it sends the current status.
PAYOUT_LINK_CLAIMED, …_COMPLETED, …_FAILED, …_CANCELLED, …_EXPIREDYour default webhook URLSecret keyA payout link changes state. The event is in event and the X-CryptoPayr-Event header.
order.completedYour platform webhook URL (Dashboard → Platform)The platform's secret keyAn order you created for a client (on_behalf_of) or a sub-account completes. See Platform webhook.
Test eventsThe test payment's webhook_url, else your defaultTest keypayment/test-complete. Body has "test": true, header X-CryptoPayr-Test: true.

Payout link payload

{
  "event": "PAYOUT_LINK_COMPLETED",
  "payout_link_id": "plk_8Kf3pQ9xR2mWvT1nZpLc",
  "status": "COMPLETED",
  "amount": "150.00",
  "currency": "USD",
  "label": "march-affiliate",
  "metadata": "",
  "payout_asset": "BTC",
  "payout_network": "BTC",
  "payout_address": "bc1q…",
  "payout_id": 57,
  "txid": "…",
  "timestamp": 1781049600
}
Payouts, transfers and sweeps don't send webhooks. Check them with payout/lookup, transfer/lookup or the list endpoints. Your endpoint has 15 seconds to answer (10 for payout links); answer 200 first and do slow work afterwards.

Send a buyer receipt

POST/api/v1/payment/receiptNo key

A customer email is never required to take a payment. Call this after a completed payment to email the buyer a branded receipt — it's what the hosted checkout uses when a buyer opts in. The transaction must already be COMPLETED.

FieldTypeDescription
tidstringRequired The completed transaction id.
emailstringRequired Where to send the receipt.
curl -X POST https://cryptopayr.com/api/v1/payment/receipt \
  -H "Content-Type: application/json" \
  -d '{ "tid": "8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1", "email": "[email protected]" }'

Response

{ "status": "success", "message": "Receipt sent", "data": { "tid": "8f14e45f-..." } }

Underpayments & expiry

Invoices expire 1 hour after creation. The hosted checkout shows a live countdown.

If a buyer sends less than the invoiced amount, the checkout shows the exact shortfall so they can top up to the same address. Merchants can opt to accept underpayments in the dashboard — when enabled, a short payment is marked complete and the normal webhook fires.

A customer email is never required to take a payment. After a successful payment the buyer can optionally enter their email to receive a receipt.

Popup checkout (JavaScript SDK)

Take a payment without leaving your page. Create the payment server-side (so your secret key never touches the browser), hand the returned tid to cryptopayr.js, and it opens the hosted checkout in a popup and calls you back when it completes or closes.

<script src="https://cryptopayr.com/assets/js/cryptopayr.js"></script>

The transaction id is a public, unguessable reference — it's safe to expose in the browser. Your secret API key is not; keep POST /payment/create on your backend.

Open the checkout

// 1) Your backend created the payment and returned its tid.
// 2) Open the popup for it:
CryptoPayr.open({
  tid: 'TRANSACTION_ID_FROM_YOUR_BACKEND',
  onSuccess: function (payment) {
    // Confirmed. payment = the public lookup payload (tid, status, amount, …).
    console.log('Paid!', payment);
  },
  onClose: function (info) {
    // The popup flow ended. info.status is COMPLETED | EXPIRED | CANCELLED | ABANDONED.
    if (!info.completed) console.log('Closed without paying');
  },
  onError: function (err) {
    // err.reason === 'popup_blocked' (use err.checkoutUrl as a fallback link)
    // or 'invalid_tid'.
  }
});

Or bind a button — no JS

Any element with data-cryptopayr-tid opens the popup on click and dispatches DOM events you can listen to. Add data-cryptopayr-redirect to send the buyer somewhere on success.

<button data-cryptopayr-tid="TRANSACTION_ID"
        data-cryptopayr-redirect="/thank-you">
  Pay with crypto
</button>

<script>
  document.addEventListener('cryptopayr:success', function (e) {
    console.log('Paid', e.detail);   // e.detail is the payment
  });
</script>

Callbacks

CallbackFires
onSuccess(payment)Payment confirmed (COMPLETED). payment is the public lookup payload.
onClose(info)The popup flow ended — once, after onSuccess on a paid flow. info.status is COMPLETED, EXPIRED, CANCELLED or ABANDONED; info.completed is true only when paid. Use it to re-enable your UI.
onPending(payment)Optional Once, when funds are first detected.
onError(err)The popup was blocked (err.reason === 'popup_blocked', with err.checkoutUrl as a fallback) or the tid was missing.

CryptoPayr.open() also accepts closeOnSuccess (default true), pollInterval (ms, default 2500) and width / height. It returns a handle with a close() method and the resolved checkoutUrl.

The SDK is a convenience layer over the hosted checkout and the public lookup endpoint. Your signed webhook remains the source of truth for fulfilment — always treat the webhook (not a browser callback) as the authority before releasing goods.

Pay with balance

Buyers who have their own CryptoPayr account can pay you instantly from their wallet balance instead of sending coins. When a signed-in buyer opens your checkout and their available balance covers the order, a “Pay with Balance” button appears; a confirmation page settles it off-chain in one click.

Nothing to integrate — it's automatic on the hosted checkout, including inside the popup SDK. A balance payment completes through the exact same flow as a coin payment: you're credited the order value net of the normal processing fee and receive the same signed COMPLETED webhook. Internally the pay-in is recorded as USDC on Polygon (the stablecoin form of the USD balance).

Buyers only see the button when they're logged in and hold enough balance, and a buyer can never pay their own order from balance. If a coin is pinned with pay_currency, the option is still offered from the deposit page.

Balance

GET/api/v1/balanceSecret key

Returns your current wallet balance, all USD-denominated. Authenticate with your secret API key.

curl https://cryptopayr.com/api/v1/balance \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
$b = $cp->account->balance();
echo $b['available']; // USD, withdrawable now
const b = await cp.account.balance();
console.log(b.available);
b = cp.account.balance()
print(b["available"])

Response

{
  "status": "success",
  "data": {
    "currency": "USD",
    "available": 12840.50,
    "pending": 50.00,
    "lifetime_credited": 184210.77
  }
}

available is withdrawable now; pending is reserved for in-flight payouts; lifetime_credited is everything ever credited to you, net of fees.

Account info

GET/api/v1/accountSecret key

Your own account details — including your public account id (usr_…), which others use to send you internal transfers.

curl https://cryptopayr.com/api/v1/account \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "status": "success",
  "data": {
    "account_id": "usr_AbC123…",
    "business_name": "Acme Store",
    "email": "[email protected]",
    "is_activated": true,
    "fee_percent": 1,
    "fixed_fee": 0.10,
    "fee_schedule": "current",
    "referral_code": "AbC123",
    "default_webhook": "https://acme.com/cryptopayr",
    "default_success": null,
    "default_cancel": null,
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}

Create a refund

POST/api/v1/refund/createSecret key

Refund a completed payment. We email the customer a link to choose where to receive it; funds move once they claim it. Authenticate with your standard API key.

FieldTypeNotes
tidstringRequired The payment to refund.
amountnumberOptional USD amount. Omit for the full remaining refundable amount.
emailstringOptional Defaults to the payment's stored customer email.
reasonstringOptional Note shown to the customer.
curl -X POST https://cryptopayr.com/api/v1/refund/create \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund_order_4815" \
  -d '{"tid":"8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1","amount":25,"email":"[email protected]"}'
$refund = $cp->refunds->create([
    'tid'    => $tid,
    'amount' => 25.00,               // USD; omit for the full refundable amount
    'email'  => '[email protected]',
], 'refund_order_4815');             // Idempotency-Key (optional)
const refund = await cp.refunds.create(
  { tid, amount: 25.0, email: '[email protected]' },
  'refund_order_4815'
);
refund = cp.refunds.create(
    {"tid": tid, "amount": 25.00, "email": "[email protected]"},
    idempotency_key="refund_order_4815",
)

Response

{ "status": "success", "data": { "refund_id": "…", "status": "REQUESTED", "tid": "8f14…", "claim_url": "https://cryptopayr.com/refund/…" } }

List refunds

GET/api/v1/refunds?page={n}&status={s}Secret key

Your refunds, newest first, 50 per page. Optional status: REQUESTED, PROCESSING, COMPLETED, REJECTED, CANCELLED. Same {page,per_page,total,total_pages,has_more,data[]} envelope as the other lists.

Exchange rates

GET/api/v1/ratesNo key

Every tracked coin's USD price.

GET/api/v1/rates/{COIN}No key

One coin.

curl https://cryptopayr.com/api/v1/rates/BTC

Response

{
  "status": "success",
  "data": { "currency": "BTC", "usd_rate": 68000, "base": "USD" }
}

Currency conversion

GET/api/v1/convert?from={A}&to={B}&amount={n}No key

Convert between any supported fiat/crypto pair, routed through USD. Crypto results carry 8 decimals, fiat 2.

curl "https://cryptopayr.com/api/v1/convert?from=USD&to=BTC&amount=100"

Response

{
  "status": "success",
  "data": {
    "from": "USD", "to": "BTC", "amount": 100,
    "result": 0.00147058, "rate": 0.0000147058
  }
}

Request a withdrawal

Programmatically withdraw your available balance to a crypto address. Because this endpoint moves funds out, it is authenticated with a separate withdrawal key — not your standard API key.

Generate the withdrawal key under Developers → Withdrawal key. For security only a hash is stored, so the key (wk_live_…) is shown once at generation. Regenerating invalidates the previous key immediately.
POST/api/v1/payout/createWithdrawal key
FieldTypeNotes
amountnumberRequired USD amount to withdraw from your available balance.
currencystringCoin to receive, e.g. BTC. Default USDT, which most accounts can't receive as a payout (see below).
networkstringNetwork, e.g. BTC. Default TRON.
addressstringDestination wallet address. Required unless address_id is given.
address_idintegerOptional Use a saved address book entry — its address, currency and network are used.
curl -X POST https://cryptopayr.com/api/v1/payout/create \
  -H "Authorization: Bearer wk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout_2026_11_10_001" \
  -d '{"amount":50,"currency":"BTC","network":"BTC","address":"bc1q..."}'
$payout = $cp->payouts->create([
    'amount'   => 50.00,   // USD taken from your balance
    'currency' => 'BTC',
    'network'  => 'BTC',
    'address'  => 'bc1q...',
], 'payout_2026_11_10_001');
const payout = await cp.payouts.create(
  { amount: 50.0, currency: 'BTC', network: 'BTC', address: 'bc1q...' },
  'payout_2026_11_10_001'
);
payout = cp.payouts.create(
    {"amount": 50.00, "currency": "BTC", "network": "BTC", "address": "bc1q..."},
    idempotency_key="payout_2026_11_10_001",
)

Response

{
  "status": "success",
  "message": "Payout requested",
  "data": {
    "payout_id": 42,
    "status": "PROCESSING",
    "amount": 50,
    "platform_fee": 0.5,
    "receive_estimate": 48.4,
    "currency": "BTC",
    "network": "BTC",
    "address": "bc1q..."
  }
}
Pick a coin you can be paid out in: payment/methods marks each one with payout: true. On accounts credited in USD (the default), USDT can't be sent out and is refused, even though buyers can pay you in it.

Payouts are dispatched immediately — there is no manual approval step. A successful call returns PROCESSING; on-chain confirmation moves it to COMPLETED. Your balance is checked atomically, so a payout can never exceed your available balance.

If the call fails it returns HTTP 502 with: "Something possible went wrong, your payout might have been sent, if not contact us [email protected]". In this case the withdrawal may already have been sent and your balance is not credited back — do not blindly retry; contact support to reconcile. Always send an Idempotency-Key so a retried request replays the original result instead of dispatching a second payout.

If a withdrawal whitelist is enabled on your account, the address must be one of your saved addresses.

Estimate a payout

GET/api/v1/payout/estimate?amount={n}&currency={c}&network={n}Secret key

Preview the platform fee, network fee and net "you receive" amount before sending a withdrawal — nothing is created. currency defaults USDT, network defaults TRON.

{ "status": "success", "data": { "amount": 50, "platform_fee": 0.5, "network_fee": 1.1, "receive_estimate": 48.4, "currency": "USDT", "network": "TRON" } }

List payouts

GET/api/v1/payoutsSecret key

Returns your payouts, newest first, 50 per page. This is a read endpoint — authenticate with your standard API key (not the withdrawal key).

QueryTypeNotes
pageinteger1-based page number. Default 1.
statusstringOptional Filter: PENDING, PROCESSING, COMPLETED or REJECTED.
curl https://cryptopayr.com/api/v1/payouts?page=1 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "status": "success",
  "data": {
    "page": 1,
    "per_page": 50,
    "total": 7,
    "total_pages": 1,
    "has_more": false,
    "data": [
      {
        "payout_id": 42,
        "status": "COMPLETED",
        "amount": 50.00,
        "platform_fee": 0.50,
        "receive_estimate": 48.40,
        "currency": "USDT",
        "network": "TRON",
        "address": "T...",
        "tx_hash": "9d2c…",
        "created_at": "2026-06-06T12:00:00+01:00"
      }
    ]
  }
}

Get a payout

GET/api/v1/payout/lookup?id={payout_id}Secret key

Returns a single payout you own. Authenticate with your standard API key. A payout id that isn't yours returns 404.

curl https://cryptopayr.com/api/v1/payout/lookup?id=42 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "status": "success",
  "data": {
    "payout_id": 42,
    "status": "COMPLETED",
    "amount": 50.00,
    "platform_fee": 0.50,
    "receive_estimate": 48.40,
    "currency": "USDT",
    "network": "TRON",
    "address": "T...",
    "tx_hash": "9d2c…",
    "created_at": "2026-06-06T12:00:00+01:00"
  }
}

The tx_hash is the processor/on-chain reference once the payout has been dispatched (null until then).

Payout addresses

GET/api/v1/payout-addressesSecret key

List saved addresses.

POST/api/v1/payout-addressesSecret key

Add one: currency, network, address, optional label and make_default.

DELETE/api/v1/payout-addresses?id={id}Secret key

Remove one.

Your saved address book — the same one the withdrawal endpoint can target with address_id, and that the optional withdrawal whitelist enforces.

Transfer to an account

Move balance to another CryptoPayr account instantly and for free — an internal book transfer, nothing touches the chain. Because it moves funds out of your balance, it uses your withdrawal key (wk_live_…), not your standard API key.

POST/api/v1/transfer/createWithdrawal key
FieldTypeNotes
recipientstringRequired The destination account's public id, e.g. usr_AbC123… (aliases: to, user_id).
amountnumberRequired USD amount to send from your available balance.
notestringOptional Memo (≤255 chars).
curl -X POST https://cryptopayr.com/api/v1/transfer/create \
  -H "Authorization: Bearer wk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transfer_1024" \
  -d '{"recipient":"usr_AbC123","amount":25,"note":"invoice 1024"}'
$t = $cp->transfers->create([
    'recipient' => 'usr_AbC123',
    'amount'    => 25.00,
    'note'      => 'invoice 1024',
], 'transfer_1024');
const t = await cp.transfers.create(
  { recipient: 'usr_AbC123', amount: 25.0, note: 'invoice 1024' },
  'transfer_1024'
);
t = cp.transfers.create(
    {"recipient": "usr_AbC123", "amount": 25.00, "note": "invoice 1024"},
    idempotency_key="transfer_1024",
)

Response

{
  "status": "success",
  "message": "Transfer complete",
  "data": {
    "transfer_id": "txf_AbC123…",
    "status": "COMPLETED",
    "amount": 25,
    "currency": "USD",
    "recipient": "usr_AbC123",
    "recipient_name": "Acme Store",
    "note": "invoice 1024",
    "created_at": "2026-06-08T12:00:00+01:00"
  }
}

The transfer is atomic — your balance is debited and the recipient credited in one step, or nothing happens. Insufficient balance returns 422; an unknown recipient returns 404; sending to your own account is rejected. Send an Idempotency-Key header so a retried request replays the original result instead of sending twice.

List transfers

GET/api/v1/transfers?page={n}&direction={in|out}Secret key

Your internal transfers (sent and received), newest first, 50 per page. Each row has a direction (in/out) and the counterparty account id. Authenticate with your standard API key.

Get a transfer

GET/api/v1/transfer/lookup?id={txf_…}Secret key

One transfer you're a party to (by its txf_ id). Returns 404 if you're neither sender nor recipient.

Sub-accounts

For platform accounts (marketplaces, SaaS, resellers). Create login-less merchant accounts for your clients, each with its own API key, and take a commission on every payment they receive. Authenticate with your platform's secret key; other accounts get 403.

POST/api/v1/accountsPlatform key

Create a sub-account.

GET/api/v1/accounts?page={n}Platform key

List your sub-accounts, newest first, 50 per page.

FieldTypeNotes
namestringRequired Your client's business name.
emailstringOptional A contact address for your records. Never used to sign in, and never emailed by us.
webhook_url / success_url / cancel_urlstringOptional Defaults for the sub-account's payments (http/https only).
fee_percent / fixed_feenumberOptional Our processing fee for this account. Never below 2% and $0.10; higher is allowed.
platform_fee_percentnumberOptional Your commission on each payment, 0–50%. Default 0.
platform_fee_fixednumberOptional Fixed commission in USD on top, 0–10,000. Default 0.
curl -X POST https://cryptopayr.com/api/v1/accounts \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Store","email":"[email protected]","platform_fee_percent":3}'

Response

{
  "status": "success",
  "message": "Sub-account created",
  "data": {
    "account_id": "usr_7Hq2…",
    "name": "Acme Store",
    "email": "[email protected]",
    "active": true,
    "api_key": "sk_live_…",
    "has_withdrawal_key": false,
    "fee_percent": 2,
    "fixed_fee": 0.1,
    "platform_fee_percent": 3,
    "platform_fee_fixed": 0,
    "balance": 0,
    "webhook_url": null,
    "created_at": "2026-11-10T12:00:00+00:00"
  }
}

The sub-account takes payments with its own api_key; your commission is taken from each completed payment and credited to your balance. You can also charge on its behalf with your own key and on_behalf_of on payment/create.

Manage a sub-account

GET/api/v1/accounts/lookup?account_id={usr_…}Platform key

One sub-account, including its success_url and cancel_url.

POST/api/v1/accounts/updatePlatform key

Body account_id plus any of name, email (contact address), webhook_url, success_url, cancel_url, fee_percent, fixed_fee, platform_fee_percent, platform_fee_fixed, active. Only the fields you send change. "active": false (or 0, or false in a form) switches the account off at once; true switches it back on, but can't lift a block we set.

POST/api/v1/accounts/rotate-keyPlatform key

Body account_id. Issues a new api_key; the old one stops working at once. Add "withdrawal": true to issue a withdrawal key instead (shown once).

POST/api/v1/accounts/sweepPlatform key

Body account_id, optional amount (USD; default: everything available), include_crypto and note. Moves the sub-account's balance into yours, instantly and for free.

curl -X POST https://cryptopayr.com/api/v1/accounts/sweep \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"usr_7Hq2…"}'

Response

{
  "status": "success",
  "message": "Balance swept to platform wallet",
  "data": {
    "account_id": "usr_7Hq2…",
    "reference": "txf_…",
    "amount": 412.5,
    "crypto_swept": [],
    "swept_to": "usr_AbC123…",
    "account_balance": 0
  }
}
A sweep is a normal transfer, so the sub-account's transfer limits apply (10 an hour). Sweeps have no Idempotency-Key: read account_balance before retrying.

Platform webhook

Set a platform webhook URL under Dashboard → Platform to get order.completed whenever an order you created for a client (on_behalf_of), or one of your sub-accounts' payments with a commission, completes. It is signed with your platform's secret key, the same way as payment webhooks.

{
  "event": "order.completed",
  "tid": "8f14e45f-ceea-467e-9a36-dcd1f8d7a2b1",
  "status": "COMPLETED",
  "on_behalf_of": "usr_7Hq2…",
  "amount": "149.0000",
  "currency": "EUR",
  "amount_usd": 172.32,
  "platform_fee_percent": 3,
  "platform_fee_fixed": 0,
  "commission_usd": 5.1696,
  "metadata": "order_4815",
  "timestamp": 1781049600
}

List the orders you created with GET /api/v1/transactions?role=platform; each row adds on_behalf_of and commission_usd.

SellAuth

No API work needed. SellAuth has no gateway plugin; it has a Custom Payment Method whose integration mode Redirect to URL sends the buyer to a URL of your choice with the order's values substituted. We give every account one such URL, keyed by a token, under Dashboard → Third-party integrations → SellAuth:

Custom Payment Methods require SellAuth's Business plan or higher — the option doesn't appear on lower SellAuth plans.
GET https://cryptopayr.com/api/v1/sellauth/{token}
      ?invoice={id}&ref={unique_id}&amount={price}&currency={currency}&email={email}

The buyer lands on it, we open a normal payment for your account and 302 them to the hosted checkout. The payment carries metadata = sellauth:<invoice id>:<reference>, so your webhook (if set) can match it. When the payment settles we call SellAuth's Process Invoice endpoint with the shop id and API key you saved, and the SellAuth order is marked paid and delivered — at settlement, not when the buyer reaches the return page, so a closed tab changes nothing. Without saved credentials the order waits in your dashboard for you to process it in SellAuth.

QuerySellAuth variableMeaning
invoice{id}Numeric invoice id — the one SellAuth's API processes. Required.
ref{unique_id}Public order reference shown to the buyer. Optional.
amount / currency{price} / {currency}Order total in the shop's currency; priced in USD on our side.
email{email}Buyer email, used for the receipt. Optional.
Step-by-step walkthrough of the SellAuth side, including the test order and troubleshooting: How to accept crypto payments on SellAuth.

Payment statuses

StatusMeaning
CREATEDPayment created, waiting for the customer.
PENDINGFunds seen on chain, waiting for confirmations.
COMPLETEDPaid and confirmed. The webhook has fired.
EXPIREDThe checkout expired before payment.
CANCELLEDCancelled by the customer or the merchant.

Errors & rate limits

Errors use standard HTTP status codes and a JSON body. error is a readable message; code is a stable word for the status that you can branch on.

{ "status": "failed", "error": "Invalid API key", "code": "unauthorized", "timestamp": 1781049600 }
HTTPcodeMeaning
401unauthorizedMissing or invalid key, or the wrong kind of key for this endpoint.
403forbiddenYour account can't do this (not a platform, the payment isn't yours, the account is paused).
404not_foundResource or currency not found.
405method_not_allowedWrong HTTP method, e.g. GET on a POST endpoint.
409conflictThe resource's state doesn't allow it, e.g. cancelling a completed payment, or the same Idempotency-Key is still being processed.
422invalid_requestMissing or invalid parameters.
429rate_limitedToo many requests. See below.
500server_errorSomething went wrong on our side. Safe to retry with the same Idempotency-Key.
502upstream_errorThe network side didn't answer clearly. On payout/create the payout may have been sent: don't retry with a new key, check GET /payouts or contact support.
503unavailableThat coin can't take payments right now; try another.

The code field was added on 10 Nov 2026. Older integrations that read only status and error keep working unchanged.

Rate limits

Every API response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix time). When you go over a window we return 429 with a Retry-After header.

EndpointLimit
POST /payment/create120 / min per merchant
GET /rates, /convert, /payment/lookup120 / min per IP
POST /payment/receipt20 / min per IP
Other endpoints120 / min per IP and per account

On top of that, each account (with its linked accounts) has hourly ceilings: 150 payments created over the API, 10 refunds, 10 transfers and 10 payout-link cancellations. These answer 429 with a Retry-After header in seconds.