Guide
Fulfil orders safely
Verify the webhook, confirm with a lookup, deliver what was paid.
What can go wrong
Three things to guard against when you deliver goods for a crypto payment:
- A forged request. Anyone can POST to your webhook URL. Only a valid signature proves it came from us.
- A missed webhook. We send each event once. If your server was down, you won't get it again on its own.
- A short payment. If you accept underpayments, a payment can complete with less than the order total.
1. Check the signature
Every webhook has an X-CryptoPayr-Signature header: an HMAC-SHA256 of the raw request body, keyed with your secret key. Compute it over the exact bytes you received (before any JSON parsing) and compare in constant time. The SDKs do this for you.
$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", 2002. Confirm the payment yourself
For orders where it matters, look the payment up before you deliver, and compare it with your order: same tid, status COMPLETED, same currency, and the amount you expect.
$p = $cp->payments->lookup($event['tid']);
$ok = $p['status'] === 'COMPLETED'
&& $p['currency'] === $order['currency']
&& (float) $p['amount'] >= (float) $order['total'];const p = await cp.payments.lookup(event.tid);
const ok = p.status === 'COMPLETED'
&& p.currency === order.currency
&& Number(p.amount) >= Number(order.total);p = cp.payments.lookup(event["tid"])
ok = (p["status"] == "COMPLETED"
and p["currency"] == order["currency"]
and float(p["amount"]) >= float(order["total"]))3. Deliver what was paid
A completed payment carries amount_paid and underpaid. They only differ from the order when you accept underpayments in your settings. If underpaid is true, either hold the order or deliver against amount_paid. See Handle underpayments.
4. Handle each event once
Store the tid of every payment you've fulfilled and skip it if it comes again (you can re-send events from the dashboard, and the same payment can arrive from your reconcile job). For refunds, key on refund_id: several partial refunds can share one tid.
5. Catch missed webhooks
Run a small job every few minutes for orders that are still waiting: call payment/lookup for each saved tid and fulfil the ones that are COMPLETED. Or page through GET /transactions?status=COMPLETED. Payments expire after an hour, so you only need to check recent ones.
Every delivery and its HTTP status is listed under Dashboard → Webhooks, where you can also re-send one.
6. Answer fast
Reply 200 within 15 seconds, then do slow work (emails, licence keys, shipping labels) afterwards. A timeout is logged as a failed delivery.