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)#

  1. API key — copy it from Account. It authenticates your requests and signs our webhooks. Regenerate invalidates the old key immediately (for both).
  2. 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.
  3. 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.

  4. 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 to failure_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": "…"}
  ]
}
  • status is paid or failed. These are final and never change.
  • provider and payment are set only when status is paid.
  • attempts lists 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_url landing, call GET /api/v1/checkouts/<id>/;
  • run a periodic job for orders whose checkout is still pending after ~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 402 on checkout creation.
  • POST /api/v1/checkouts/ from the backend, customer redirected to checkout_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.