Hosted Payment Page Quickstart

Hosted Payment Page (HPP) is the shortest integration path. Flowlix renders the card form; your server creates a Payment, redirects the customer’s browser, and retrieves the Payment for the authoritative result.

When to use HPP

Choose HPP when raw card numbers and CVC values must not enter your checkout or backend. Your merchant server does not send card data in an HPP request. Your server still owns order fulfilment, idempotency, and final-status handling.

Prerequisites

Complete the shared setup in Authentication.

1. Create a Payment

curl -X POST "$FLOWLIX_BASE_URL/v1/payments/hpp" \
  -H "Authorization: Bearer $FLOWLIX_API_KEY" \
  -H "Idempotency-Key: order-2345678901-hpp-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "EUR",
    "merchant_reference": 2345678901,
    "customer_ip_address": "203.0.113.7",
    "return_url": "https://shop.example/checkout/complete"
  }'

Field	Requirement
`amount`	Positive integer in the currency’s minor units.
`currency`	Three-letter ISO 4217 code.
`customer_ip_address`	The shopper’s literal IPv4 or IPv6 address, without a hostname, port, or proxy chain.
`return_url`	Your absolute page URL for the browser return. It is not a payment-result callback.
`merchant_reference`	Optional 10-digit integer for reconciliation; it does not deduplicate requests.

Optional billing and customer fields can prefill the hosted form. The API reference contains the complete request schema.

2. Store the response and redirect

A create returns 201 Created with the current Payment state. Store its id before taking further action. The initial state is one of:

Status	What to do now
`PENDING`	Do not redirect or resubmit. Retrieve this Payment for its latest recorded state.
`REQUIRES_ACTION`	Redirect the browser to the returned `next_action.redirect_url`.
`FAILED`	Do not redirect. Read `failure_code`; a new customer attempt creates a new Payment.

For example, a Payment ready for the hosted browser flow is:

{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 2500,
  "currency": "EUR",
  "status": "REQUIRES_ACTION",
  "integration_type": "HOSTED_PAYMENT_PAGE",
  "next_action": {
    "type": "redirect",
    "reason": "hosted_payment_page",
    "redirect_url": "https://hosted-payment.example/redirect-token"
  },
  "amount_refunded": 0,
  "amount_refundable": 0,
  "livemode": false,
  "created_at": 1719792000
}

Redirect only when the response has status: REQUIRES_ACTION, and use the exact opaque next_action.redirect_url. Flowlix collects the card details on the hosted page. 3D Secure may be presented during that hosted flow when required by the payment provider. A PENDING or FAILED response has no immediate shopper redirect. For Sandbox card entry and authentication scenarios, see test cards and 3DS cases. While the Payment is REQUIRES_ACTION, retrieve it periodically. If its latest next_action.redirect_url changes, send the browser to the new URL. Do not repeatedly redirect the same browser to an unchanged URL.

3. Handle the browser return

Flowlix sends the customer to return_url after the hosted browser flow.

Reaching return_url does not confirm payment. Never fulfil an order from a query parameter or browser state. Retrieve the Payment from your server.

4. Confirm the final status

export PAYMENT_ID="pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"

curl "$FLOWLIX_BASE_URL/v1/payments/$PAYMENT_ID" \
  -H "Authorization: Bearer $FLOWLIX_API_KEY"

Repeat the retrieval while the Payment is PENDING, REQUIRES_ACTION, or PROCESSING. Stop when it reaches:

Status	Action
`SUCCEEDED`	Fulfil the order and retain the Payment ID for reconciliation.
`FAILED`	Read `failure_code`; offer a new Payment attempt when appropriate.
`EXPIRED`	Create a new Payment if the customer restarts checkout.

For polling intervals and every status, see Payment lifecycle.

Safe retries

If the create request times out or returns a transient HTTP error, retry with the same Idempotency-Key and an equivalent effective request identity. A changed business attempt uses a new key. See Idempotency.

Next steps

Create a Refund after a test Payment succeeds.
Submit and retrieve a Payout.
Receive Payment and Refund events.
Add complete API error handling.

Get started

Build with Flowlix

Handle failures

API reference

Hosted Payment Page Quickstart

When to use HPP

Prerequisites

1. Create a Payment

2. Store the response and redirect

3. Handle the browser return

4. Confirm the final status

Safe retries

Next steps

​When to use HPP

​Prerequisites

​1. Create a Payment

​2. Store the response and redirect

​3. Handle the browser return

​4. Confirm the final status

​Safe retries

​Next steps

When to use HPP

Prerequisites

1. Create a Payment

2. Store the response and redirect

3. Handle the browser return

4. Confirm the final status

Safe retries

Next steps