CryptoPayr Docs
Dashboard Get API key

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.

Don't fulfil the order when the buyer reaches 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", 200

Answer 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.