Skip to main content
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": "ord_5678",
    "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"
  }'
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",
    "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. 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 processing. 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.