Offer - advanced settings

The Advanced tab in the offer form (create and edit) holds checkout settings not tied directly to price or promotions. Each field below is documented in the same order as in the form. Settings apply to this offer only and affect the /pay page, embedded checkout, and schedule-related payments.

Allowed payment methods

Controls which payment methods the customer sees on this offer's payment page. Options:

• BLIK and Card - both methods available to the payer.
• BLIK - BLIK only (requires an active Tpay account for the organization).
• Card - card only (Stripe integration).

At least one method must be enabled. Without active Tpay, BLIK options are unavailable and card is the default.

Fallback offers on payment error

Fallbacks run when the first payment attempt in a checkout flow ends with a terminal Tpay failure (FAILED). The system maps the Tpay error to a rule condition; if a rule matches, the customer moves to a backup path instead of a dead-end error screen.

Fallbacks do not apply to: merchant onboarding errors, refunds, automatic subscription renewals, or operations outside the first payment in the current checkout.

Enable and rules

• Enable Fallback offers on payment error.
• Add rules: Condition + Redirect to. On first enable: Any payment failure → Offer (pick a fallback offer).
• Rules are evaluated top to bottom - first match wins.

Redirect to - types

The Redirect to field defines what happens after a rule matches. There are three action types - each described below.

Offer

The customer is sent to another offer you select - its payment page (/pay) opens in the same browser tab. You cannot pick the current offer; the fallback offer must belong to the same organization.

On the target offer checkout, its own price, promotions, and allowed payment methods apply. The customer completes payment as a normal purchase of that offer - e.g. pays by card when BLIK failed on the original offer, or picks a cheaper backup plan without BLIK subscription.

Referrals, referral codes, and promotions from the original link are not carried over (parameters such as ref are intentionally omitted). The other offer has its own referral program and promotions - you avoid attributing commission or discounts to the wrong product.

Checkout context that helps the payer finish purchase is passed via the URL parameter zfc: the id points to data stored in sessionStorage (email, name, invoice details, consents, newsletter opt-in). The customer usually does not need to re-enter them. Full integration metadata from the original session is not copied - only payer UX context is transferred.

When redirecting to a fallback offer, tracking parameter sfa=1 (fallback attempt) is added, which feeds Fallback successes in Analytics → Sources.

URL

The customer is sent to a custom HTTPS URL you provide (landing page, help page, your own form) in the same tab. Zevio does not host that page - you control what the customer sees after the error.

The URL receives query parameters from the current payment session (UTM campaign, source params, etc.), except offer signature (sig), offer id (qrId), referral links (ref), payment ids, and checkout session ids. A short checkout context is also appended as zfc (same as for Offer).

Manual BLIK

Manual BLIK is a backup mode for BLIK subscriptions (models A, M, or O). On a normal first subscription payment, Zevio tries to register a BLIK alias with the customer's bank so later charges can run automatically without a 6-digit code. When the bank does not support recurring BLIK and Enable BLIK manual recurring for unsupported banks is off (default), the first payment is rejected - without a fallback rule the customer sees a hard error and the subscription does not start.

A Manual BLIK rule does not move the customer to another offer or URL. They stay on the same offer and payment page; the address gets blikManualFallback=1. Checkout switches to one-time BLIK (eBLIK): the customer enters a standard 6-digit code from the banking app, like a regular one-off BLIK payment, instead of alias registration flow.

In manual mode, usually only BLIK is shown (card is hidden) to keep the backup path simple. After a successful payment the subscription may still be created, but later renewals at banks without alias support require confirming each charge with a BLIK code again (Zevio sends email reminders with a payment link). Typical rule condition: Bank does not support recurring BLIK.

The payment screen shows Back to standard payment - it removes manual mode from the URL and restores normal checkout (retry BLIK alias or card if available). Referral/promo parameters from the original link remain, because the customer is still on the same offer.

Works on /pay, merchant pay dashboard, and embedded checkout - wherever payment fallbacks are supported.

Error conditions

• Any payment failure
• Bank does not support recurring BLIK (typical with Manual BLIK)
• Invalid or expired BLIK code
• Declined in banking app
• Declined by bank or card issuer
• Insufficient funds
• Transaction limit exceeded
• BLIK confirmation timed out
• BLIK declined by bank (alias or security)
• Bank or payment channel unavailable
• Technical error or no response

Transition screen before redirect

Separate switch below the rules. When enabled, the customer sees an interstitial with an error explanation and a countdown (~10 s) before continuing (/payment/redirect or /checkout/redirect). On by default when fallbacks are enabled; can be turned off.

Enable BLIK manual recurring for unsupported banks

Available only when BLIK subscription is enabled (Basic tab). Off by default (strict mode applies). Controls the first BLIK subscription payment when the customer's bank does not support recurring BLIK (no payId): on - we run manual recurring for that bank (payment succeeds, later periods after a reminder); off - the first payment is rejected.

Zevio sends Tpay the refuseNoPayId flag according to this setting. After the customer enters a BLIK code, Tpay returns payIdEligible in the createTransaction response (typically within ~1 s), indicating whether the bank supports a recurring alias. Zevio uses that signal to pick the subscription type and next steps - without making the customer wait for the alias registration webhook.

When enabled - permissive mode (manual recurring)

• The offer stores paymentFallbacks.refuseNoPayId: false.
• Tpay receives refuseNoPayId: false - the first BLIK payment may succeed even when the bank does not support recurring.
• Bank supports recurring (payIdEligible: true) - subscription is `BLIK_RECURRING`, automatic renewals (BLIK alias).
• Bank does not support recurring (missing or false payIdEligible) - subscription is `BLIK_MANUAL_RECURRING`: first charge is one-time BLIK, later periods require the customer to pay via email reminders (link with blikManualFallback=1).
• On the success page the customer may see a notice that the bank does not support recurring BLIK and that Zevio will send reminders (URL param blikRecurringManual=1).

Permissive mode helps close conversion for customers at banks without a BLIK alias without forcing an error screen and a Manual BLIK fallback rule - a reminder-based subscription is created right after a successful first payment.

When disabled (default) - strict mode

• Tpay receives refuseNoPayId: true (the default when the field is not set).
• Bank supports recurring BLIK (payIdEligible: true) - first payment succeeds, subscription is `BLIK_RECURRING`, later charges are automatic (BLIK alias).
• Bank does not support recurring BLIK - first payment is rejected, no subscription is created.
• The customer sees an error on the payment page - unless a fallback rule runs (e.g. Manual BLIK), switching them to one-time BLIK on the same offer.

Strict mode fits when you want automatic BLIK alias subscriptions only and accept declined first payments at banks without recurring support (Revolut and similar), unless you configure a fallback.

Permissive mode vs Manual BLIK rule

• Enable BLIK manual recurring for unsupported banks on (permissive) - bank without payId: payment succeeds immediately, manual recurring subscription, no fallback redirect.
• Manual BLIK rule - runs after a terminal first-payment failure (typical when strict rejects the bank); customer gets blikManualFallback=1 on the same offer and enters a one-time BLIK code.
• Both end with a `BLIK_MANUAL_RECURRING` subscription, but the customer path differs: automatic (permissive) vs after error (fallback).
• The Manual BLIK rule still makes sense with the toggle off (strict mode) - e.g. strict by default with a backup conversion path for selected error conditions.

Late alias registration

If the subscription was created as `BLIK_MANUAL_RECURRING` (bank initially without payId) and Tpay later sends an `ALIAS_REGISTER` webhook, Zevio stores the alias and upgrades the subscription method to `BLIK_RECURRING`. Later periods may then run automatically - without changing the offer configuration.

Reminders and cancellation (manual recurring)

In the form: Manual renewal payment reminders and Cancel after unpaid days. Positive offsets are days before due date, 0 is the due day, negative (e.g. -1) are days after. A post-due reminder must be earlier than cancellation. Empty list defaults to the day before and the due day. In the REST API: recurring.manualRenewalPolicy.notifyDaysBefore and recurring.manualRenewalPolicy.cancelAfterDaysUnpaid (1-30 days).

REST API

In the offer `paymentFallbacks` object (POST/PUT /qr): optional field `refuseNoPayId`. When `false`, permissive mode is enabled (UI toggle Enable BLIK manual recurring for unsupported banks = on). When the field is omitted, the default strict mode applies (toggle off).

Analytics

Analytics → Sources → Fallback successes; tracking parameter slfa=1.

Recurring payment retries

Fields available only when subscription is enabled (Basics tab). They apply to automatic charges with a BLIK alias (BLIK_RECURRING) when a subsequent recurring payment fails.

• Retry count after failed payment (recurring.retryPolicy.maxAttempts) - how many times the system retries an automatic charge after a failed attempt (1-10, default 3). After the limit is exhausted the subscription is cancelled.
• Interval between retries (recurring.retryPolicy.intervalDays) - how many days to wait before the next automatic attempt (1-14, default 1).

In the REST API set recurring.retryPolicy on POST /qr, PUT /qr/{qrId}, POST /payments, and POST /checkout-sessions. When omitted, defaults are maxAttempts: 3 and intervalDays: 1.

Purchase country selector

When enabled, the customer sees a purchase country select on checkout above payment methods. The country affects tax ID / VAT validation and payment fiscal context.

• Enable selector (countrySelect.enabled) - shows the country list to the payer.
• Default country (countrySelect.defaultIso2) - ISO 3166-1 alpha-2 code pre-selected (e.g. PL, DE). Empty means Poland (PL).

Country priority: when the customer enters a tax ID / VAT number, that country wins; without a tax ID the selected country is used; when the selector is off - geolocation.

In the REST API set countrySelect on POST /qr, PUT /qr/{qrId}, POST /payments, and POST /checkout-sessions.

Lead collection during payment

Configures extra fields and consents on the payment page. Data flows to payments, subscriptions, webhooks, and the Leads module.

Collect company data at payment

When enabled, checkout shows I want an invoice. When checked, tax ID, company name, street, postal code, and city are required. Data is stored on payments, subscriptions, and webhooks.

Override default terms text

When enabled, you can replace the default Zevio terms with custom HTML (Custom terms text). HTML tags allowed, e.g. links <a href="...">.

Terms checkbox

• Show terms checkbox - displays the default (or overridden) terms checkbox at payment.
• Required checkbox - customer must accept terms before paying (when the checkbox is shown).

Additional consents

List of custom consent checkboxes (e.g. marketing, privacy policy). For each consent:

• Consent ID - stable identifier (max 64 chars) stored in checkoutDetails.consents and webhooks; must be unique and not reserved for terms.
• Consent text (HTML) - text shown to the payer.
• Show checkbox / Required checkbox - same as for terms.

Multiple subscriptions per customer

Available only when subscription is enabled (Basic tab). Controls whether the same customer may hold multiple concurrent subscriptions for this offer, or the rule is one subscription per customer with automatic resume of a cancelled / ended subscription instead of creating a new one.

In the REST API, set recurring.allowMultipleSubscriptions on POST /qr and PUT /qr/{qrId}. The field is returned in GET responses inside recurring.

When the option is on

The same customer may purchase multiple concurrent subscriptions for the same offer (e.g. family plans, multiple seats, repeat buys). Checkout does not intercept payments for resume - each payment may create a new subscription.

When the option is off (default)

Each customer may have at most one subscription for the offer. Buying a cancelled subscription again (scheduled cancellation or already ended) resumes the existing one on the same subscriptionId instead of creating a second. COMPLETED, EXPIRED, and subscriptions with allowResume = false (e.g. after archiving a recurring offer) are out of scope.

When a subscription is resumable

• PENDING_CANCELLATION or cancelAtPeriodEnd = true - cancellation scheduled at the end of the paid period; access still continues.
• CANCELLED with endedAt set and cancelAtPeriodEnd = false - the subscription has already ended.
• Required: allowResume !== false and a match of customer (customerId) to offer (qrId).

Variant 1: scheduled cancellation (PENDING_CANCELLATION)

• Amount due today: 0 - payment-method registration / refresh only (card token or BLIK alias).
• Payment type: subscription_resume (path / initiation kind SUBSCRIPTION_RESUME).
• Effect: clear cancellation flags (cancelAtPeriodEnd, canceledAt, currentPeriodEnd), restore TRIAL or ACTIVE from promotions and cycle payment count.
• Next payment date: unchanged - keeps the existing nextPaymentDate.
• Promotions: the 0-amount payment does not consume trial or other payment-count promotions.

Variant 2: ended subscription (CANCELLED)

• Amount due today: the reactivation invoice (like the next cycle) - applies remaining offer and subscription promotions (trial, discounts, coupons, referral).
• Payment type: subscription_reactivate (also path SUBSCRIPTION_RESUME).
• Effect: re-attach payment method, settle the amount, continue lifecycle on the same subscriptionId.
• Next payment date: resume day + interval (e.g. resume on 10 Aug with 1M → next 10 Sep). Does not restore the pre-cancel calendar. Explicit offer monthlyAnchorDay if set; otherwise anchor from the resume day.
• Promotions: counter = successful cycle payments (excluding subscription_resume and contents proration). If trial is “2 payments” and one was used, 1 remains; when exhausted - catalog / base price.

Where the flow appears

• Offer payment page (`/pay`) - for an identified customer, checkout intercepts payment creation and starts resume. The offer includes resumableSubscriptionId, resumeTotalDueToday, resumeNextPaymentDate, resumeCompletedPaymentCount. Breakdown (net, VAT, discount, “valid for N payments”, next payment date) matches normal checkout with remaining promotions; in sandbox - from the subscription simulation clock.
• Merchant dashboard - subscription details - Resume subscription when status allows and allowResume permits. Modal: amount due today (0 or reactivate invoice), promotions, and next payment date - aligned with /pay.
• Customer portal (session) - Resume for resumable rows; same amount and date rules.

Payments, path, and history

• Subscription payment history and the payments list show Path (initiationKind) as Resume (SUBSCRIPTION_RESUME).
• subscription_resume (0 due) does not bump completedOccurrences or consume trial. subscription_reactivate counts as a cycle payment. The cycle counter stays aligned with successful cycle payments (excluding 0-amount resume and contents proration).
• A new resume attempt while a previous resume is PENDING cancels the old PENDING (supersede) and starts a fresh one.

Webhooks on successful resume

Expected order: payment.pending → payment.success → a single subscription.updated (TRIAL/ACTIVE, etc.). No earlier clear-cancel-only subscription.updated. Payload may include paymentId and paymentProcessedAt after payment success. See Webhooks docs.

Time simulation (sandbox / test)

When a subscription has a simulation clock, the reactivate invoice and next payment date on /pay and in details are computed from the simulation date (e.g. simulated 5 Sep with 1M → next 5 Oct), not wall-clock “today”.

Subscription cancellation lock

Available only when subscription is enabled (Basic tab). Sets the minimum period from subscription start during which the customer cannot cancel in the customer portal. After that period, cancellation is unlocked.

• No restrictions - customer can cancel anytime (default).
• Presets - month, quarter, half year, year.
• Other - custom count and unit (days, weeks, months, years).

The organization can cancel a subscription in the dashboard at any time, regardless of the lock.

Offer group

Links this offer with other variants of the same product (e.g. Basic / Pro plans). A group may contain at most 3 offers including the current one. All offers must belong to the same organization.

Offers in the group

Select up to 2 other offers (offerGroupMemberQrIds) that together with the current one form the group. After save, members are returned on the offer as offerGroupResolved.members.

Checkout switching

When Allow switching between offers at checkout is on (offerGroup.switchingEnabled, on by default), the customer sees variant options with amounts on the payment page and can pick another group member - the page reloads to that qrId.

Plan change on an active subscription

When Allow customers to change plan on an active subscription is on (offerGroup.subscriptionSwitchingEnabled), the customer sees a plan-change section in the subscription portal. The organization always sees this option in the dashboard.

In the offer panel and API set offerGroupMemberQrIds and optionally offerGroup (switchingEnabled, subscriptionSwitchingEnabled) when creating or updating an offer (POST /qr, PUT /qr/{qrId}).

Retention offer (anti-churn)

Available only when recurring is enabled with BLIK model M or O. When a customer cancels a subscription on this offer, instead of ending immediately the system can propose switching to another offer (cheaper plan, annual variant, etc.).

• Enable retention offer (recurring.retentionOffer.enabled).
• Target offer (recurring.retentionOffer.targetQrId) - an offer in the same organization the customer can switch to instead of cancelling.

The proposal appears in the customer portal during subscription cancellation. Choosing the retention plan switches the subscription to the target offer instead of cancelling.

When creating or updating an offer set recurring.retentionOffer (POST /qr, PUT /qr/{qrId}).

Thank you page

Controls what the customer sees after a successful payment on /pay or embedded checkout. Three modes:

• Default - Zevio success screen with standard title, description, and actions.
• External URL - optional HTTPS redirect after success. When set, the customer is sent to your page instead of the Zevio screen.
• Customize default page - keep the Zevio success screen but override title, description, and an optional button (label + URL). Set button.enabled to false to hide the button and default actions.

In the REST API use successUrl for external redirect and resultPages.success for customization. In responses, customization is returned under links.resultPages.success on the offer.

In embedded checkout (iframe/popup), postMessage events are sent to the parent page: CHECKOUT_STARTED when the customer submits payment, and CHECKOUT_SUCCESS on final success, regardless of a custom URL.

Error page

Controls what the customer sees after payment cancel or error when a fallback did not run (or fallbacks are not configured). Three modes:

• Default - Zevio error screen with standard title, description, and actions.
• External URL - optional HTTPS redirect after failure or cancel.
• Customize default page - keep the Zevio error screen but override title, description, payment retry (retryEnabled), and an optional button (label + URL).

In the REST API use cancelUrl for external redirect and resultPages.failed for customization (including retryEnabled). In responses, customization is returned under links.resultPages.failed on the offer.

Embedded checkout sends postMessage events to the parent page: CHECKOUT_STARTED when the customer submits payment, and CHECKOUT_FAILED on final error or cancel. A custom error URL triggers an additional redirect only when the URL is provided.

Metadata

Key-value pairs (up to 50 entries, key max 255 chars) passed to payments, checkout sessions, and webhooks: payment.success, payment.failed, qr.created, qr.updated. Examples: order_id, cart_id, source - useful for CRM, ERP, or custom backend integrations.

Stripe report

Toggle enables reporting this offer's transactions to Stripe. Available only when the organization has an active Stripe integration (Developers → Stripe). Disabled when Stripe is not configured.