Skip to main content
With the Hosted Payment Page (HPP), Flowlix renders the card form. Your integration never sees card data, which keeps you out of PCI DSS scope for cardholder data handling.

​
How it works

​
1. Create the payment

Field notes:
  • billing_details is required: at minimum the customer’s email and address (line1, city, postal_code, country). The values you send prefill the hosted page. If the customer edits them there, the customer-entered values become authoritative for the payment.
  • return_url is where the customer is sent after completing or abandoning the page.
  • merchant_reference is an optional integer with exactly 10 digits (from 1000000000 to 9999999999) that ties the payment to your order for reconciliation. Several payment attempts may share one merchant_reference (for example when a customer retries after a decline) — it does not deduplicate requests. Use the Idempotency-Key header for that; see Idempotency.

​
2. Redirect the customer

The response contains next_action:
Redirect the customer’s browser to next_action.redirect_url when next_action.reason is hosted_payment_page, using an HTTP 303 redirect or a client-side navigation. The page handles card entry, validation, and 3D Secure authentication when the issuer requires it. After the customer submits card details, the payment can stay REQUIRES_ACTION with next_action.reason: "three_d_secure". Keep polling GET /v1/payments/{id} while the customer is waiting. If Flowlix returns a different next_action.redirect_url, redirect the customer to that latest URL. If the URL is unchanged for the same browser session, avoid redirecting in a loop and keep showing a pending confirmation state.

​
3. The customer returns

After the customer pays — or cancels, or the page expires — Flowlix redirects them to your return_url.
Never fulfil an order based on the customer reaching return_url. Query parameters appended to the return URL are UX hints only. The payment status from GET /v1/payments/{id} or a webhook event is the single source of truth.
Recommended handling on your return page:
  1. Look up the payment ID you stored when creating the payment (keyed by your order/session, not by URL parameters).
  2. Call GET /v1/payments/{id}.
  3. Render the result:
    • SUCCEEDED — show the confirmation page and fulfil the order.
    • REQUIRES_ACTION — the hosted page completion has not been reconciled yet, or a follow-up 3D Secure browser action is required. Redirect to a new next_action.redirect_url when it changes; otherwise show a “payment confirmation pending” page and keep polling (or wait for the webhook). See Payment lifecycle for polling guidance.
    • FAILED — show the failure message and offer to retry with a new payment. The failure_code tells you why; see Operation failure codes.
    • EXPIRED or CANCELED — the customer did not complete the page; offer to start a new payment.

​
Page lifetime

A hosted payment page is single-use and tied to one payment attempt. If the customer does not complete it before it expires, the payment transitions to EXPIRED and the link stops working — create a new payment for another attempt.

​
Customization

The hosted page automatically adapts to the customer’s device and locale. Branding options (logo, accent color) are managed in the Merchant Portal.