Integration Quickstart

Create your API key in Zevio under Developers → REST API → API Keys. Copy it once and store it somewhere safe (password manager or secrets vault). Never paste it into a mobile app shipped to customers or commit it to GitHub.

Every automated call uses your environment’s API host with paths starting with /api/v1/. The REST documentation page in the dashboard shows the full base URL next to API Keys.

Use different keys and expectations for test vs live: match whatever you choose with the Sandbox / Production switch in the app so test traffic never hits production money.

An “offer” is the product or service you charge for: price, currency, optional subscription rhythm, return URLs after pay/cancel, and which payment methods are allowed.

Easiest path: create it under Offers in the dashboard. You can also create or update offers through the REST API (/api/v1/qr…) - parameters and responses are in the interactive REST docs.

Each offer gets a stable id (qrId). You will reuse that id when you generate payment links, start checkout sessions from an offer, and when you match webhook events back to what was sold. Put your own order number in metadata if you need to reconcile with your shop or ERP.

Most integrations choose one of two patterns: a hosted Zevio page (the shopper follows a URL returned by the API) or an embedded checkout (the shopper stays on your site inside an iframe).

Hosted page - call POST /api/v1/payments/{qrId} with your API key. The response includes link and destinationLink: link is the single URL you hand to the shopper (it reaches checkout and is counted); destinationLink is the full URL of the payment page on the Zevio front end (often {your Zevio web}/pay/...).

Embedding - create a session with POST /api/v1/checkout-sessions or POST /api/v1/checkout-sessions/from-qr/{qrId}. The response gives embedUrl to load in an iframe (typically {your Zevio web}/checkout/{sessionId}) and destinationEmbedUrl, the direct checkout view URL for the iframe. How to finish the journey on your side and which callbacks apply are described under Checkout in the REST docs.

Zevio keeps customers in your organization's scope and assigns each one a stable customerId. Map that id to your own user or CRM record so payments, subscriptions, and webhooks always refer to the same person.

On the payment-link call you may send customerId or a customer object with email (plus optional names and language). Without a known customerId, Zevio matches or creates a customer by email within your organization - when identity resolves, the response includes customer with customerId; store it for later calls. On checkout session create, the same customer block lands in session metadata and is echoed under metadata in the first response; a stable customerId often appears only after a successful payment - read it from payment.success webhooks or payment detail APIs. On either path you can attach metadata with your own order or cart id so it flows through exports and later events.

To create a customer record explicitly from your backend (outside those flows), use POST /api/v1/customers - fields and rules are in the REST docs.

The customer portal (self-service on Zevio-hosted screens) starts with POST /api/v1/customer-portal-sessions; request and response fields are documented next to that route in the REST explorer.

Instead of constantly asking "did anything change?", Zevio can POST JSON to a URL you host when something important happens (payment succeeded, subscription lifecycle changes, and so on).

Register your HTTPS endpoint under Developers → Webhooks and choose which events you want. How to configure URLs and secrets is covered in the Webhooks documentation in the dashboard.

Each POST includes x-zevio-event and x-zevio-signature, with JSON fields event, data, and timestamp. Confirm authenticity with your endpoint secret and the raw request body - the Webhooks documentation gives the signature rules and examples. Deliveries may repeat; track data.id so your integration handles each logical event once.

Making integration coherent. The data object carries the operational context for each event (alongside the generated delivery id).

Payments. For payment.success, payloads typically include paymentId, qrId, customerId, amounts and currency; recurring charges usually also carry subscriptionId. Any metadata you attached when creating the payment link or checkout session is echoed back - map your ERP or storefront order id from there. Fulfill idempotently (for example by paymentId or a key taken from metadata) and persist customerId / the customer block on your side. payment.failed, payment.cancelled, and payment.pending let you reflect failure, cancellation, or in-flight state without polling.

Subscriptions. subscription.created includes subscriptionId, qrId, customerId, the initial paymentId, and offer context - persist the recurring agreement keyed by customerId. When the offer has promotional trial pricing enabled, data.status may be TRIAL until the trial window ends, then ACTIVE. subscription.updated fires on recurring payments and other lifecycle changes (including TRIAL→ACTIVE, cancel-at-period-end, resume). subscription.canceled, subscription.expired, and subscription.completed mark closure or end-of-cycle - align product access or billing with status and timestamps in the payload.

Embedded checkout. checkout_session.created and checkout_session.completed complete the iframe flow with session and payment identifiers plus echoed metadata - useful alongside payment.success when you finalize carts from both hosted links and embedded checkout.

Automation can fail or arrive late. Use the product as the human backstop:

• Analytics - trends and totals over time.
• Subscriptions and payments → Payments - individual payment attempts and statuses.
• Subscriptions and payments → Subscriptions - recurring agreements and whether they match what webhooks told you.

After you change code or credentials, spot-check here before you rely on it for real money.

Walk through the whole journey with Sandbox turned on: separate data, separate keys, same ideas as production. Use the Sandbox instruction panel inside the app for test card numbers, BLIK rules, and odd amounts; those rules change more often than this page.

This Quickstart is the map. The built-in REST explorer lists every parameter and sample response. The Webhooks section lists event names and example payloads. While you integrate, keep Subscriptions and payments (Payments and Subscriptions views) and Analytics within reach.