Quickstart
From an account to a paid test payment and a verified webhook. Everything here uses a test key, so no real money moves.
On this page
1. Get an account
Access is by request: send the form on the home page. The request goes to the operator, and an account exists only once the operator has created it. Then sign in to your dashboard.
2. Create API keys
In your dashboard, open API keys and create a test key. A test key starts with cp_test_, a live key with cp_live_.
Test and live are separate worlds: a test key sees only test payments and a live key only live ones. See Test mode.
3. Create a payment
Send the price, a description shown to the buyer and the return_url the buyer goes back to. Amounts are decimal strings in major units, never numbers. The Idempotency-Key makes a retry safe: send the same key again after a timeout and you get the same payment back, not a second one.
curl -sS https://payments.example.com/api/v1/payments \
-H "Authorization: Bearer cp_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-42-attempt-1" \
-d '{
"amount": "49.00",
"currency": "EUR",
"description": "Order 42",
"return_url": "https://shop.example.com/thanks",
"metadata": { "order_id": "42" }
}'The answer is 201 with the payment. Keep its id with your order.
{
"id": "pay_0123456789abcdefghjkmnpq",
"object": "payment",
"status": "created",
"amount": "49.00",
"currency": "EUR",
"description": "Order 42",
"metadata": {
"order_id": "42"
},
"checkout_url": "https://payments.example.com/pay/3vQB7B6MrGQHehYtG8JNQSjQdXbNUjpkLUWGDKvvQdk",
"livemode": false,
"expires_at": "2026-11-07T12:00:00.000Z"
}Replace https://payments.example.com/api/v1 with the /api/v1 URL of your gateway host in every sample of these docs.
4. Send the buyer to the checkout
Redirect the buyer to checkout_url. The buyer chooses a method and pays there, then comes back to your return_url with ?payment=<id> added.
In test mode there is no real provider. Open the checkout, choose a method, then follow the link to the test controls and mark the payment paid, failed or expired. The payment then moves through the same code as a live one.
5. Handle the webhook
In your dashboard, open Webhooks and add a test endpoint: an https:// URL on a public host. Copy its signing secret (whsec_...); like an API key it is shown once.
Each event arrives as a POST with a CP-Signature header. Verify it against the raw body before anything else:
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 5 * 60;
/** rawBody: the request body as a string, exactly as received. */
export function verifyWebhook(secret, header, rawBody, nowSeconds = Math.floor(Date.now() / 1000)) {
const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
if (!match) return false;
const timestamp = Number(match[1]);
if (Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) return false;
const expected = createHmac('sha256', secret).update(`${match[1]}.${rawBody}`).digest();
const given = Buffer.from(match[2], 'hex');
return given.length === expected.length && timingSafeEqual(given, expected);
}Then:
- Answer with any 2xx status quickly, and do the work after you answer.
- Drop duplicates by the event
id: an event can arrive more than once. - Read the payment with
GET /v1/payments/{id}and act on the status the API returns.
Webhooks has the full event catalogue, the retry schedule and the delivery rules.
6. Go live
When the test flow works end to end, create a live key and a live webhook endpoint, and work through the go-live checklist.