> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowlix.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted Payment Page Quickstart

> Create a Sandbox payment, redirect the customer, and confirm the final Payment status

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](/guides/authentication).

## 1. Create a Payment

```bash theme={null}
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](/payments-api/payments/create-a-hosted-payment-page-payment)
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:

```json theme={null}
{
  "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](/guides/testing#test-cards).

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.

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

## 4. Confirm the final status

```bash theme={null}
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](/guides/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](/guides/idempotency).

## Next steps

* [Create a Refund](/guides/refunds) after a test Payment succeeds.
* [Submit and retrieve a Payout](/guides/payouts).
* [Receive Payment and Refund events](/guides/webhooks).
* Add complete [API error handling](/guides/errors).