Quickstart

This guide takes you from zero to a completed test payment using the 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.

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

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.

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:

{
  "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, 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.

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.

4. Confirm the payment status

Retrieve the payment and check its status:

curl https://api.flowlix.dev/v1/payments/pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E \
  -H "Authorization: Bearer api_test_sk_abc123def456"

{
  "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 for every status and how to react to it. For real-time updates without polling, subscribe to webhooks.

Next steps

Hosted Payment Page in depth

Prefilling, return URL semantics, expiry, and edge cases.

Direct API integration

Charge cards from your own checkout UI (PCI DSS required).

Webhooks

Get notified the moment a payment succeeds or fails.

Refunds

Return funds to your customers, fully or partially.

Get started

Guides

Error handling

Payments API

Prerequisites

1. Create a hosted payment page payment

2. Redirect your customer

3. Handle the return

4. Confirm the payment status

Next steps

Hosted Payment Page in depth

Direct API integration

Webhooks

Refunds

​Prerequisites

​1. Create a hosted payment page payment

​2. Redirect your customer

​3. Handle the return

​4. Confirm the payment status

​Next steps

Hosted Payment Page in depth

Direct API integration

Webhooks

Refunds

Prerequisites

1. Create a hosted payment page payment

2. Redirect your customer

3. Handle the return

4. Confirm the payment status

Next steps