Payments
Hosted checkout at /pay with amount, project, and opaque data.
Pay URL
Redirect the customer to the SDK host pay page with query parameters:
/pay?amount=10&project=PROJECT_ID&data=OPAQUE_ORDER_DATA&customId=ORDER_123- amount — Integer Perper amount as a query string (e.g. 10). The portal submits it as a decimal string to the backend.
- project — Your project id (cuid2).
- data — Opaque string you define (e.g. order id). Passed through so your backend can correlate the payment.
- customId (optional) — Merchant idempotency key. Hosted /pay forwards it to Contabo (same as Contabo QR). Required later for checkStatus; echoed on webhook + redirect.
Checkout UX
The pay page shows the project name and amount. The payer confirms with Pay. On success, the portal follows the redirect URL returned by the Perper backend. On failure, an error is shown.
Success page
/pay/successful confirms a completed send when the flow lands there. Prefer fulfilling orders from your apiUrl callback rather than trusting the browser alone.
Server callback (apiUrl)
Perper POSTs a signed JSON result to your apiUrl. The browser return URL is UX only — fulfill from a verified webhook. Full contract, verify recipe, and live proof live under Webhooks.
Transaction status (API)
POST /sdk/transaction/checkStatus with projectId, customId, and a JWT hash signed with the project secret returns { successful: boolean }. Hash payload is { projectId, customId } — not the opaque pay data string.
QR pay link (API)
POST /sdk/project/qr (authenticated owner) returns a PNG QR pointing at the hosted /pay URL for amount + project (+ data/customId). The portal forwards those query params into Contabo pay so QR → /pay → checkStatus compose.
Example (Node)
function buildPayLink({ host, amount, projectId, orderId }) {
const url = new URL("/pay", host);
url.searchParams.set("amount", String(amount));
url.searchParams.set("project", projectId);
url.searchParams.set("data", orderId);
url.searchParams.set("customId", orderId); // optional — enables checkStatus
return url.toString();
}Create projects and copy a sample URL from the project detail page after quickstart. Quickstart · Webhooks.