Merchant integration#
Payment Cascade connects your shop to Klarna, Riverty, Scalapay and Alma through a single API. Your backend creates a checkout with the order items, customer details and callback URLs, then redirects the customer to the link we return. We offer the order to your connected providers in the order you set in your account; if a provider declines, we try the next one. When the order is paid, or every provider has declined, we call your webhook and send the customer back to your shop.
Your backend Payment Cascade Providers
│ POST /api/v1/checkouts/ │ │
│ ───────────────────────────────>│ │
│ 201 { checkout_url, ... } │ │
│ <───────────────────────────────│ │
│ │ │
Customer ── redirect to checkout_url ─>│── provider 1 ────────────────>│
│ │<─ refused / cancelled ────────│
│ │── provider 2 ────────────────>│
│ │<─ paid ───────────────────────│
│ POST webhook_url (signed) │ │
│ <───────────────────────────────│ │
Customer <── redirect to success_url ──│ │
1. Setup (account page)#
- API key — copy it from Account. It authenticates your requests and signs our webhooks. Regenerate invalidates the old key immediately (for both).
- Integrations — connect providers with your provider credentials. The order of the cards is the cascade order (top is tried first); reorder with ↑ / ↓. For Riverty, give Riverty the webhook URL shown on its card.
-
Store currency — the currency of the prices you send. Auto picks it from the customer's country (DE → EUR, SE → SEK, GB → GBP, US → USD, …). Set it explicitly if your prices are always in one currency.
-
Billing — the service is paid per order: one request is spent when a checkout ends paid; failed and abandoned checkouts are free. New accounts get a few free requests for testing. Buy a pack of requests on the account page with Оплата по ссылке (BSB_Link!) (pay by link); the balance and recent charges are shown there. With a zero balance, new checkouts are refused with
402(checkouts already started still complete).
GET /api/v1/payments/providers/ returns the current cascade:
{"providers": ["klarna", "riverty"]}.
2. Authentication#
Every API request carries your key in one of these headers:
Authorization: Api-Key <your-api-key>
X-Api-Key: <your-api-key>
Call the API from your backend only — never expose the key in the browser.
A missing or wrong key returns 401.
3. Create a checkout#
POST /api/v1/checkouts/
Content-Type: application/json
Authorization: Api-Key <your-api-key>
{
"order_id": "A-1001",
"items": [
{"name": "Running shoes", "quantity": 2, "unit_price": 4999, "tax_rate": 1900, "sku": "SH-42"},
{"name": "Socks", "quantity": 1, "unit_price": 990}
],
"customer": {
"email": "anna@example.de",
"first_name": "Anna",
"last_name": "Muster",
"phone": "+4915112345678",
"address": {
"street": "Hauptstraße",
"house_number": "1",
"line2": "",
"postcode": "10115",
"city": "Berlin",
"country": "DE"
},
"shipping_address": null
},
"callbacks": {
"success_url": "https://shop.example/order/A-1001/thanks",
"failure_url": "https://shop.example/order/A-1001/payment-failed",
"webhook_url": "https://shop.example/hooks/payment-cascade"
}
}
Fields#
| Field | Required | Notes |
|---|---|---|
order_id |
no | Your order reference, ≤ 200 chars. Generated (order-…) when omitted. Returned in every response and webhook. |
items[] |
yes | 1–200 items. |
items[].name |
yes | ≤ 255 chars. |
items[].quantity |
yes | 1–10 000. |
items[].unit_price |
yes | Gross price (tax included) in minor units: 4999 = 49.99. |
items[].tax_rate |
no | Percent × 100: 1900 = 19 %. Default 0. |
items[].sku |
no | ≤ 64 chars. |
customer.email |
yes | |
customer.first_name, last_name |
yes | |
customer.phone |
no | International format recommended; some providers require it. |
customer.address |
yes | Billing address. street, postcode, city, country (ISO 3166-1 alpha-2) are required; house_number, line2 optional. |
customer.shipping_address |
no | Same shape. Defaults to address. |
callbacks.success_url |
yes | Customer lands here after a successful payment. |
callbacks.failure_url |
yes | Customer lands here when no provider accepted the order. |
callbacks.webhook_url |
yes | Receives the final result (section 5). Must be a publicly reachable URL; use https. |
Everything else — order total, tax totals, currency, provider region and
language — is computed by us. Unknown fields are rejected, so don't send
provider-specific fields (order_amount, purchase_currency, provider, …).
Response — 201 Created#
{
"checkout_id": "5b0f1c1e-8a7e-4c39-9c55-3c1f0f8a2d11",
"order_id": "A-1001",
"status": "pending",
"amount": 10988,
"currency": "EUR",
"checkout_url": "https://paycascade.io/pay/5b0f1c1e-8a7e-4c39-9c55-3c1f0f8a2d11/",
"providers": ["klarna", "riverty", "scalapay"],
"provider": null,
"payment": null,
"attempts": []
}
Store checkout_id with your order and redirect the customer to
checkout_url. Check that amount and currency match your order.
Errors#
| Status | Meaning |
|---|---|
400 |
Validation error. detail is a list of {"type", "loc", "msg"} entries, e.g. {"loc": ["customer", "email"], "msg": "Field required"}. Also returned when you have no connected providers or webhook_url is not public. |
401 |
Missing or invalid API key. |
402 |
No paid requests left. Top up on the account page. |
4. What the customer sees#
- We send the customer to the first provider in your cascade.
- If that provider refuses the order, errors out, or the customer cancels or goes back, we immediately move on to the next provider.
- While a provider confirms the payment, the customer sees a short "processing" page that refreshes automatically.
- When a provider confirms the payment, the customer is redirected to
success_url. When every provider has failed, the customer goes tofailure_url.
Opening checkout_url again (refresh, second tab) continues the same
checkout; it never starts a second payment. A checkout pays at most once.
The redirect to success_url is only a UX signal — don't fulfil the order on
it. Use the webhook or GET /api/v1/checkouts/<id>/.
5. Webhook#
When the checkout finishes, we POST the checkout object (same shape as the
API response) to webhook_url exactly once:
{
"checkout_id": "5b0f1c1e-8a7e-4c39-9c55-3c1f0f8a2d11",
"order_id": "A-1001",
"status": "paid",
"amount": 10988,
"currency": "EUR",
"checkout_url": "https://paycascade.io/pay/5b0f1c1e-.../",
"providers": ["klarna", "riverty", "scalapay"],
"provider": "riverty",
"payment": {
"payment_id": "9c4e…",
"order_id": "A-1001__riverty",
"operation_id": "A-1001",
"provider": "riverty",
"status": "paid",
"amount": 10988,
"currency": "EUR",
"provider_order_id": "…"
},
"attempts": [
{"payment_id": "1a2b…", "provider": "klarna", "status": "cancelled", "error": "Customer returned with outcome=cancel"},
{"payment_id": "9c4e…", "provider": "riverty", "status": "paid", "error": ""},
{"payment_id": null, "provider": "scalapay", "status": "refused", "error": "…"}
]
}
statusispaidorfailed. These are final and never change.providerandpaymentare set only whenstatusispaid.attemptslists every provider we tried, for your support and analytics.
Reply with any 2xx within 5 seconds. Redirects are not followed.
Verify the signature#
Each webhook carries two headers:
X-Webhook-Timestamp: 1763457600
X-Webhook-Signature: 3f7a… (hex)
X-Webhook-Signature = hex(HMAC-SHA256(key = your API key, message = "<timestamp>." + raw request body))
Compute it over the raw body bytes (before JSON parsing), compare in constant time, and reject timestamps older than 5 minutes.
Python:
import hashlib, hmac, time
def verify(raw_body: bytes, timestamp: str, signature: str, api_key: str) -> bool:
if abs(time.time() - int(timestamp)) > 300:
return False
expected = hmac.new(
api_key.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
Node.js:
const crypto = require("crypto");
function verify(rawBody, timestamp, signature, apiKey) {
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = crypto.createHmac("sha256", apiKey)
.update(`${timestamp}.`).update(rawBody).digest("hex");
return expected.length === signature.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
PHP:
function verify(string $rawBody, string $timestamp, string $signature, string $apiKey): bool
{
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
return false;
}
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $apiKey);
return hash_equals($expected, $signature);
}
// In your webhook endpoint:
$rawBody = file_get_contents('php://input');
$ok = verify(
$rawBody,
$_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '',
$_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '',
getenv('PAYMENT_CASCADE_API_KEY')
);
if (!$ok) {
http_response_code(401);
exit;
}
$checkout = json_decode($rawBody, true);
http_response_code(204);
Delivery is not retried#
The webhook is sent once. If your endpoint was down, read the result from the API (section 6). We recommend:
- on the
success_url/failure_urllanding, callGET /api/v1/checkouts/<id>/; - run a periodic job for orders whose checkout is still
pendingafter ~1 hour.
Handle the webhook idempotently by checkout_id.
6. Read a checkout#
GET /api/v1/checkouts/<checkout_id>/
Authorization: Api-Key <your-api-key>
Returns the same object as the webhook. status is pending until the
checkout finishes. Checkouts of other merchants return 404.
Single attempts can be inspected with GET /api/v1/payments/<payment_id>/.
7. Testing#
Connect the providers with their sandbox credentials in Integrations and
create checkouts against your own test shop. When you run this service locally
(DEBUG=True), the /demo/ page is a working shop that sends exactly the
requests described above.
Checklist#
- API key stored on the backend only.
- Providers connected and ordered; Riverty webhook URL registered with Riverty.
- Store currency set if your prices are in a fixed currency.
- Request balance topped up; your backend handles
402on checkout creation. POST /api/v1/checkouts/from the backend, customer redirected tocheckout_url.- Webhook signature and timestamp verified on the raw body.
- Order fulfilled only on
status: "paid"(webhook or API), idempotently. - Reconciliation via
GET /api/v1/checkouts/<id>/for missed webhooks.