Take USDT and USDC payments anywhere.
A REST API with JSON in and out. Create a payment from your server, send the customer to the checkout, and get a signed webhook when it is paid.
https://…/v1What you can build
Online stores and appsCharge in USDT, USDC, USD or PKR. USD and PKR prices are converted and the customer picks the coin.
Payment linksA page anyone can pay, with a fixed price or any amount, without code.
Refunds and payoutsSend money back to customers, or out to any CryptoCash ID or crypto address.
Several storesOne business, many stores. Each has its own keys and webhooks.
Build your integration
Answer three questions and get one complete file: it creates the payment, sends the customer to the checkout, and verifies the webhook. Put your keys in environment variables and run it.
Then try it without a customer: the sandbox runs the same calls from this page, and Test on your machine sends a signed webhook to this file on localhost.
Sandbox
Try the API right here, before you write any code. The sandbox only accepts test keys, so nothing here moves real money. Your key stays in this browser tab and is sent only to this site's /v1.
No key yet? Create a free account, then Developers → API keys → Test.
Pick a step and press Send.
—
Test on your own machine
While you build on localhost, CryptoPay cannot reach your computer, so webhooks will not arrive by themselves. There are two simple ways to work:
- Ask instead of waiting. After the customer returns, call
GET /v1/payments/{id}. During development you can also readGET /v1/eventsto see every event that would have been sent. - Replay a real event to localhost. Take an event from your test account, sign it with your webhook secret, and post it to your local server. The tool below builds the exact command.
- Use a tunnel (ngrok, Cloudflare Tunnel) when you want live deliveries: put the tunnel address in Developers → Webhooks → Test URL.
The secret is used in this tab to sign the event. It is not sent anywhere.
Your command appears here.
2xx within 10 seconds and verify the CryptoPay-Signature header exactly as shown under Verify signatures. A replayed event carries a fresh timestamp, so the five-minute check passes. On Windows, run the command in Git Bash or WSL (PowerShell handles the quotes differently).Authentication
Send your secret key as a Bearer token on every request. Keys start with sk_test_ or sk_live_ and belong to one store.
Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc…
The full key is shown once when you create it. We store only a hash.
Test and live mode
Test sk_test_
- No real money moves.
- The checkout has buttons to simulate paid, failed and expired.
- Open from the first minute.
Live sk_live_
- Real USDT and USDC.
- Opens after your business is verified.
- Same code: you only change the key.
Test keys create test payments: the checkout shows a TEST MODE banner and buttons to simulate success, failure and expiry, and no real money moves (a wallet payment in test mode does not change the payer's balance). Everything else works exactly like live, including webhooks.
Live keys open after your business verification is approved. Each object carries "mode": "test" or "live".
Errors
Successful requests answer 200. Errors answer 4xx or 5xx with this body:
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "amount must be a positive number such as \"25.00\"",
"param": "amount",
"request_id": "req_8fK2pQ…"
}
}
| HTTP | type | When |
|---|---|---|
| 400 | invalid_request_error | A parameter is missing or wrong. param names it. |
| 401 | authentication_error | No key, a malformed key or a revoked key. |
| 403 | permission_error | Suspended account, live mode before verification, IP not allowed, payouts off. |
| 404 | invalid_request_error | resource_missing or endpoint_not_found. |
| 409 | invalid_request_error / idempotency_error | duplicate_order_id, payment_not_open, or an Idempotency-Key reused with a different body. |
| 429 | rate_limit_error | More than 300 requests a minute on one key. |
| 5xx | api_error | Our side. Retry with the same Idempotency-Key. |
Every answer has a Request-Id header. Quote it when you contact support; it is also in your dashboard's API logs.
Idempotency
Send an Idempotency-Key header with any POST, for example your order number. If the network fails and you retry with the same key and the same body, you get the first answer back (with header Idempotent-Replayed: true) instead of a second payment. Keys are kept for 24 hours. The same key with a different body answers 409.
-H "Idempotency-Key: order-1001"
Pagination
List endpoints return newest first:
{ "object": "list", "data": [ … ], "has_more": true }
| Parameter | Description |
|---|---|
| limit | 1 to 100, default 20. |
| starting_after | An object id. Returns the objects after it (older). Use the last id of the page you have. |
| created_gte, created_lte | Unix seconds. |
Rate limits
300 requests a minute per key. Answers carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Above the limit you get 429; wait and retry.
Versions
Every answer and every event carries api_version. We may add new fields and new event types at any time, so ignore anything your code does not know. A change that could break working code gets a new version date; the current one is shown at the top of this guide.
The payment object
{
"id": "pay_7Kc2Lx9Qe4WmRt1Bz8NvYs",
"object": "payment",
"mode": "live",
"status": "paid",
"amount": "4500.00",
"currency": "PKR",
"pay_amount": "15.845071",
"pay_currency": "USDT",
"accepted_tokens": ["USDT", "USDC"],
"exchange_rate": "284",
"fee": "0.158451",
"net_amount": "15.68662",
"refunded_amount": "0.00",
"order_id": "1001",
"description": "Leather wallet",
"items": [{ "name": "Leather wallet", "quantity": 1, "price": "4500" }],
"customer": { "email": "sara@example.com" },
"metadata": { "cart": "77" },
"checkout_url": "{{BASE}}/checkout/pay_7Kc2Lx9Qe4WmRt1Bz8NvYs",
"return_url": "https://yourstore.com/thanks",
"cancel_url": null,
"payment_method": "wallet",
"network": null,
"txid": null,
"payment_link": null,
"source": "api",
"created": 1763700000,
"expires_at": 1763701800,
"paid_at": 1763700125,
"closed_at": 1763700125,
"failure_reason": null
}
All amounts are strings with exact decimals: never parse them into floating point for money maths. pay_amount is what the customer pays in the token; net_amount is what reaches your balance after the fee.
Status
| status | Meaning |
|---|---|
| open | Waiting for the customer. Can be cancelled. |
| confirming | The customer sent crypto on-chain; it is being confirmed. Do not ship yet. |
| paid | Money is in your balance. Ship the order. refunded_amount shows partial refunds. |
| refunded | Fully refunded. |
| expired | Not paid before expires_at. |
| cancelled | You cancelled it. |
| failed | An on-chain transfer could not be confirmed. See failure_reason. |
Create a payment
| Parameter | Description |
|---|---|
| amountrequired | Decimal string, e.g. "25.00".string |
| currency | USDT (default), USDC, USD or PKR. USD is paid 1:1 in USDT or USDC. PKR is converted at the platform's buy rate, locked when the payment is created.string |
| order_id | Your order number, up to 64 characters. One open or paid payment per order id.string |
| description | Shown to the customer. Up to 300 characters.string |
| items | Up to 50 { "name", "quantity", "price" }, shown on the checkout. Display only; amount is what is charged.array |
| customer | { "name", "email", "phone", "reference" }. Never shown on the checkout.object |
| metadata | Up to 20 keys of your own data, returned as is.object |
| accepted_tokens | Limit USD / PKR payments to ["USDT"] or ["USDC"].array |
| return_url | Where the customer goes after paying. We add ?payment_id=…&status=paid. Defaults to the store's return URL.string |
| cancel_url | Where "Cancel and return" goes.string |
| expires_in | Minutes, 5 to 10080. Default 30.integer |
// Node.js 18+
const r = await fetch('{{BASE}}/v1/payments', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.CRYPTOPAY_SECRET_KEY, 'Content-Type': 'application/json', 'Idempotency-Key': 'order-1001' },
body: JSON.stringify({ amount: '4500', currency: 'PKR', order_id: '1001', description: 'Leather wallet', return_url: 'https://yourstore.com/thanks' })
});
const payment = await r.json();
if (!r.ok) throw new Error(payment.error.message);
// redirect the customer to payment.checkout_url
<?php // PHP
$ch = curl_init('{{BASE}}/v1/payments');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CRYPTOPAY_SECRET_KEY'), 'Content-Type: application/json', 'Idempotency-Key: order-1001'],
CURLOPT_POSTFIELDS => json_encode(['amount' => '25.00', 'currency' => 'USDT', 'order_id' => '1001'])]);
$payment = json_decode(curl_exec($ch), true);
header('Location: ' . $payment['checkout_url']);
# Python
import os, requests
payment = requests.post('{{BASE}}/v1/payments',
headers={'Authorization': 'Bearer ' + os.environ['CRYPTOPAY_SECRET_KEY'], 'Idempotency-Key': 'order-1001'},
json={'amount': '25.00', 'currency': 'USDT', 'order_id': '1001'}).json()
Retrieve a payment
Always check the status on your server before you ship, e.g. when the customer lands on your return_url.
List payments
Filters: status, order_id, plus the pagination parameters. GET /v1/payments?order_id=1001 finds the payment for an order.
Cancel a payment
Only open payments. A confirming payment cannot be cancelled because the customer already sent money.
Hosted checkout
The checkout_url page shows your store name, the amount, items and a countdown, and offers:
- CryptoCash app: no password on your site. The customer scans the QR with the app, or types their 8-digit CryptoCash ID and approves the request on their phone, or on a phone taps "Open CryptoCash app". They confirm with their PIN or fingerprint. Instant, no network fee.
- Send USDT / USDC: the exact amount, the address and a QR code per network. The customer pastes the transaction hash; the payment becomes
confirmingand thenpaidonce confirmed.
After paying, the customer is sent to your return_url with payment_id and status. Treat those as a hint only: confirm with the webhook or GET /v1/payments/{id}.
Checkout on your page
Keep the customer on your site: the checkout opens on top of your page.
<script src="{{BASE}}/js/pay.js"></script>
<script>
// id comes from your server: POST /v1/payments
CryptoPay.checkout({
payment: 'pay_7Kc2Lx9Qe4WmRt1Bz8NvYs',
onSuccess: (p) => location.href = '/thanks?payment=' + p.id,
onCancel: (p) => console.log('not paid', p.status),
onClose: () => console.log('closed')
});
</script>
<!-- or with no code at all -->
<button data-cryptopay="pay_7Kc2Lx9Qe4WmRt1Bz8NvYs" data-success-url="/thanks">Pay with crypto</button>
CryptoPay.checkout also takes { url } with a checkout or payment-link address, and closeOnBackdrop: true. CryptoPay.close() closes it.
In your own mobile app
Open the checkout_url in Chrome Custom Tabs (Android) or SFSafariViewController (iOS): the "Open CryptoCash app" button then opens the customer's CryptoCash app, they confirm with their PIN, and come back to the checkout, which already shows the result. If you use a plain WebView instead, pass links that are not http(s) to the system so the CryptoCash app can open:
// Android WebView
webView.setWebViewClient(new WebViewClient() {
@Override public boolean shouldOverrideUrlLoading(WebView v, WebResourceRequest r) {
Uri u = r.getUrl();
if ("cryptocash".equals(u.getScheme())) { startActivity(new Intent(Intent.ACTION_VIEW, u)); return true; }
return false;
}
});
Confirm the order on your server with the webhook or GET /v1/payments/{id}, as on the web.
Refunds
| Parameter | Description |
|---|---|
| paymentrequired | The payment id. |
| amount | Default: everything not yet refunded. Partial refunds are allowed. |
| reason | Shown to the customer. |
| network, address | Needed only when the payment was paid on-chain: where to send the refund (minus the network fee). |
Wallet payments are refunded to the customer's wallet at once (succeeded). On-chain refunds are processing until our team sends them, then succeeded (with txid) or failed. The amount comes out of your balance.
Payment links
| Parameter | Description |
|---|---|
| titlerequired | Shown on the page. |
| amount, currency | Leave out amount to let the customer choose. |
| description | Optional text. |
| max_uses | Stop after this many paid payments. |
| collect | { "name": true, "email": true, "phone": false }: what the customer must enter. |
| after_payment_url | Where the customer goes after paying. |
Each payment made through a link is a normal payment with payment_link set. Turn a link off with { "active": false }.
Balance
{ "object": "balance", "mode": "live",
"available": [{ "currency": "USDT", "amount": "1520.40" }, { "currency": "USDC", "amount": "310.00" }],
"pending": [{ "currency": "USDT", "amount": "25.00" }, { "currency": "USDC", "amount": "0.00" }] }
pending is on-chain payments still confirming. Your balance is shared by all your stores.
Payouts
{ "amount": "100", "currency": "USDT", "destination": { "type": "cryptocash", "id": "12345678" } }
{ "amount": "100", "currency": "USDT", "destination": { "type": "crypto", "network": "TRC20", "address": "T…" } }
To a CryptoCash ID: instant and free (paid). To a crypto address: processing until sent, then paid with txid, or failed (the amount returns to your balance). Networks: TRC20, BEP20, ERC20, SOL, APTOS, BASE.
Rates and ping
/v1/rates gives the current PKR per dollar used for PKR prices. /v1/ping checks your key and tells you its store and mode.
Events and webhooks
Every change creates an event. Add an endpoint per mode in the dashboard (Developers → Webhooks) and we POST each event to it:
POST /your/webhook
CryptoPay-Signature: t=1763700125,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
CryptoPay-Event: payment.paid
CryptoPay-Event-Id: evt_3Hk…
{ "id": "evt_3Hk…", "object": "event", "type": "payment.paid", "mode": "live", "api_version": "2026-11-21",
"created": 1763700125, "data": { "object": { "id": "pay_…", "object": "payment", "status": "paid", … } } }
- Answer any
2xxwithin 10 seconds. Do slow work after answering. - Otherwise we retry 8 times: after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h. You can resend any event from the dashboard.
- Events can arrive more than once or out of order. Use
event.idto skip ones you have seen, and the object'sstatusas the truth. GET /v1/eventsandGET /v1/events/{id}list events and their delivery status.
If your server does not answer
Verify signatures
Compute HMAC-SHA256 of t + "." + raw body with your store's signing secret (whsec_…) and compare it with v1. Reject events older than 5 minutes. Use the raw body exactly as received, before any JSON parsing.
// Node.js (Express)
const crypto = require('crypto');
app.post('/cryptopay/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const m = /t=(\d+),v1=([0-9a-f]+)/.exec(req.get('CryptoPay-Signature') || '');
const raw = req.body.toString();
const want = m && crypto.createHmac('sha256', process.env.CRYPTOPAY_WEBHOOK_SECRET).update(m[1] + '.' + raw).digest('hex');
if (!m || Math.abs(Date.now() / 1000 - m[1]) > 300 || !crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]))) return res.sendStatus(400);
const event = JSON.parse(raw);
if (event.type === 'payment.paid') fulfil(event.data.object.order_id);
res.sendStatus(200);
});
<?php // PHP
$raw = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([0-9a-f]+)/', $_SERVER['HTTP_CRYPTOPAY_SIGNATURE'] ?? '', $m);
$want = $m ? hash_hmac('sha256', $m[1] . '.' . $raw, getenv('CRYPTOPAY_WEBHOOK_SECRET')) : '';
if (!$m || abs(time() - (int)$m[1]) > 300 || !hash_equals($want, $m[2])) { http_response_code(400); exit; }
$event = json_decode($raw, true);
if ($event['type'] === 'payment.paid') fulfil($event['data']['object']['order_id']);
# Python (Flask)
import hmac, hashlib, re, time, os
@app.post('/cryptopay/webhook')
def hook():
raw = request.get_data()
m = re.match(r't=(\d+),v1=([0-9a-f]+)', request.headers.get('CryptoPay-Signature', ''))
want = m and hmac.new(os.environ['CRYPTOPAY_WEBHOOK_SECRET'].encode(), m[1].encode() + b'.' + raw, hashlib.sha256).hexdigest()
if not m or abs(time.time() - int(m[1])) > 300 or not hmac.compare_digest(want, m[2]):
return '', 400
event = request.get_json()
return '', 200
Event types
| type | When |
|---|---|
| payment.created | A payment was created (API, dashboard or link). |
| payment.confirming | The customer sent crypto on-chain; waiting for confirmation. |
| payment.paid | Ship the order. Money is in your balance. |
| payment.failed | An on-chain transfer was not confirmed. |
| payment.expired | Not paid in time. |
| payment.cancelled | You cancelled it. |
| refund.created | A refund was created. |
| refund.succeeded | The refund reached the customer. |
| refund.failed | The refund could not be sent; the amount is back in your balance. |
| payout.created | A payout was created. |
| payout.paid | It arrived. |
| payout.failed | It was not sent; the amount is back in your balance. |
| test.ping | Sent by "Send test event" in the dashboard. |
Testing
- The fastest way to try everything is the sandbox on this page. For webhooks on localhost see Test on your machine.
- Use a
sk_test_key. Open thecheckout_url: the test tools simulate success, failure and expiry. - Paying on-chain in test mode with any transaction hash marks the payment paid at once. The address shown is a placeholder: never send real crypto in test mode.
- Test refunds and payouts change only your test balance.
- Your dashboard shows every request (API logs) and every webhook delivery with your server's answer.
Go-live checklist
- Business verification approved (dashboard → Business verification).
- A live secret key on your server, in an environment variable.
- A live webhook endpoint on https, verifying signatures and skipping duplicate events.
- You ship only on
payment.paid(or a server-side GET showingpaid). - Idempotency-Key on every POST. Optional: IP allowlist for your servers.
Security
- Keys are stored hashed and shown once. Revoke and replace a key any time; old keys stop at once.
- Every live action in the dashboard that moves money asks for your password again.
- Webhooks are signed per store; roll the secret if it leaks.
- Customer card or wallet passwords never reach your site: wallet sign-in happens on the CryptoCash checkout.
- Report a problem to the support team from the dashboard (Account → Help and support).