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

# Quickstart

> Accept your first payment in five minutes with the Hosted Payment Page

This guide takes you from zero to a completed test payment using the
[Hosted Payment Page](/guides/hosted-payment-page) — the integration path that
requires no PCI compliance on your side.

## Prerequisites

* A Flowlix merchant account with access to the Merchant Portal.
* Your **test secret key** (`api_test_sk_...`) from the Developers section of
  the Merchant Portal.
* `curl` or any HTTP client.

<Warning>
  Secret keys must only be used from your servers. Never embed them in mobile
  apps, browsers, or public repositories.
</Warning>

## 1. Create a hosted payment page payment

Call `POST /v1/payments/hpp` with the amount (in minor units), the customer's
billing details, and a `return_url` — the page on your site where the customer
lands after paying.

```bash theme={null}
curl -X POST https://api.flowlix.dev/v1/payments/hpp \
  -H "Authorization: Bearer api_test_sk_abc123def456" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "EUR",
    "merchant_reference": 2345678901,
    "billing_details": {
      "email": "jenny@example.com",
      "address": {
        "line1": "Kurfuerstendamm 21",
        "city": "Berlin",
        "postal_code": "10719",
        "country": "DE"
      }
    },
    "return_url": "https://shop.example.com/checkout/complete"
  }'
```

`merchant_reference` is optional and must be an integer with exactly 10 digits
(from `1000000000` to `9999999999`).

The API responds with `201 Created` and a Payment object:

```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://pay.flowlix.dev/hpp/pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"
  },
  "livemode": false,
  "created_at": 1719792000,
  "amount_refunded": 0,
  "amount_refundable": 0
}
```

## 2. Redirect your customer

Send the customer to `next_action.redirect_url` when `next_action.reason` is
`hosted_payment_page`. Flowlix renders a secure, mobile-friendly payment page
where they enter their card details.

In test mode, pay with a [test card](/guides/testing), for example
`4111 1111 1111 1111` with any future expiry date and any CVC.

## 3. Handle the return

After the customer completes (or abandons) the page, Flowlix redirects them to
your `return_url`.

<Warning>
  The redirect to `return_url` is a UX signal only — it does not confirm
  payment. The customer may close the browser before the redirect, or the
  payment may still be waiting for provider reconciliation. Always confirm the
  outcome with the API.
</Warning>

## 4. Confirm the payment status

Retrieve the payment and check its `status`:

```bash theme={null}
curl https://api.flowlix.dev/v1/payments/pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E \
  -H "Authorization: Bearer api_test_sk_abc123def456"
```

```json theme={null}
{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "status": "SUCCEEDED",
  "card": { "brand": "visa", "last4": "1111", "exp_month": 12, "exp_year": 2027 },
  "amount_refundable": 2500,
  "...": "..."
}
```

`SUCCEEDED` means the funds were collected — you can fulfil the order. See
[Payment lifecycle](/guides/payment-lifecycle) for every status and how to
react to it. For real-time updates without polling, subscribe to
[webhooks](/guides/webhooks).

## Next steps

<CardGroup cols={2}>
  <Card title="Hosted Payment Page in depth" href="/guides/hosted-payment-page" icon="globe">
    Prefilling, return URL semantics, expiry, and edge cases.
  </Card>

  <Card title="Direct API integration" href="/guides/direct-api" icon="server">
    Charge cards from your own checkout UI (PCI DSS required).
  </Card>

  <Card title="Webhooks" href="/guides/webhooks" icon="bell">
    Get notified the moment a payment succeeds or fails.
  </Card>

  <Card title="Refunds" href="/guides/refunds" icon="rotate-ccw">
    Return funds to your customers, fully or partially.
  </Card>
</CardGroup>