Guide
Your first payment in 5 minutes
Create a payment, send the buyer to checkout, get the webhook.
1. Get your keys
Sign up, then open Dashboard → Developers. You get two keys to start with:
sk_test_…, the test key. Use it while you build; nothing it does touches real money.sk_live_…, the secret key. Use it in production. It also signs your webhooks.
Keep both on your server. Never put them in a browser, an app or a public repository.
2. Create a payment on your server
When the buyer clicks "Pay with crypto", create a payment for the order total. Put your order number in metadata so you can match it later, and send an Idempotency-Key so a retry never opens a second payment.
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"]The answer holds a tid (save it with the order) and a checkout_url.
3. Send the buyer to the checkout
Redirect the buyer to checkout_url. They pick a coin and network, see the address and amount, and pay from their wallet. When the payment is confirmed they're sent to your success_url.
success_url: anyone can open that page. Wait for the webhook in the next step. Prefer to keep buyers on your page? The popup checkout opens the same checkout in a window.4. Fulfil the order on the webhook
When the payment is confirmed on chain, we POST a COMPLETED event to your webhook_url. Check the signature, then mark the order paid.
$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", 200Answer 200 quickly. The webhook is sent once and not retried, so also read Fulfil orders safely for the checks that catch a missed one.
5. Test it, then go live
Run the same code with your sk_test_ key, then make the test payment complete with one call. Your webhook gets a real, signed event.
# 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"})When it works, swap in your sk_live_ key. The going-live checklist lists what else to check.