Skip to main content
POST
/
v1
/
payments
/
hpp
Create an HPP payment
curl --request POST \
  --url https://api.flowlix.eu/v1/payments/hpp \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 2500,
  "currency": "eur",
  "customer": {
    "email": "alex@example.com",
    "first_name": "Alex",
    "last_name": "Johnson",
    "country": "DE",
    "phone": "+491709876543",
    "address": "Friedrichstrasse 100",
    "city": "Berlin",
    "zip": "10117"
  },
  "redirect_url": "https://shop.example.com/checkout/complete"
}
'
{
  "id": "pay_1N4gLy3fAvLZmn3D1YkNs9qW",
  "object": "payment",
  "amount": 2500,
  "currency": "eur",
  "status": "pending",
  "description": null,
  "card": null,
  "customer": {
    "email": "alex@example.com",
    "name": "Alex Johnson"
  },
  "metadata": {},
  "decline_code": null,
  "decline_message": null,
  "redirect_url": "https://pay.flowlix.eu/hpp/pay_1N4gLy3fAvLZmn3D1YkNs9qW",
  "refunded_at": null,
  "succeeded_at": null,
  "failed_at": null,
  "created": 1719792000,
  "livemode": false
}

Authorizations

​
Authorization
string
header
required

Use your secret API key as the Bearer token. Test mode keys start with fl_test_sk_ and live mode keys start with fl_live_sk_.

Authorization: Bearer fl_test_sk_abc123def456

Headers

​
Idempotency-Key
string

A unique key to ensure the request is processed only once. If a request with the same idempotency key has already been processed, the original response is returned. Keys expire after 24 hours. We recommend UUIDv4 values.

Maximum string length: 255
​
Flowlix-Version
string

The API version to use for this request. Defaults to your account's default version if not specified. Format: YYYY-MM-DD.

Pattern: ^\d{4}-\d{2}-\d{2}$

Body

application/json
​
amount
integer<int64>
required

The payment amount in minor units. For EUR, 2500 means EUR 25.00.

Required range: x >= 1
Example:

2500

​
currency
string
required

Three-letter ISO 4217 currency code in lowercase.

Required string length: 3
Pattern: ^[a-z]{3}$
Example:

"eur"

​
redirect_url
string<uri>
required

The URL to redirect the customer to after payment completion or abandonment. Flowlix appends ?payment_id={id}&status={status} as query parameters.

Example:

"https://shop.example.com/checkout/complete"

​
customer
object
​
description
string

An arbitrary string to attach to the payment for your records.

Maximum string length: 500
Example:

"Order #5678"

​
metadata
object

A set of key-value pairs for storing additional information about the payment. Keys and values are strings. Maximum 50 keys.

Example:
{ "order_id": "ord_5678" }
​
callback_url
string<uri> | null

An optional server-to-server callback URL. Flowlix will POST the payment result to this URL when the payment completes.

Example:

null

Response

HPP payment session created.

A Payment object represents a single attempt to move money. It is created when you submit a payment request and is updated as the payment progresses through its lifecycle.

​
id
string

Unique identifier for the payment.

Pattern: ^pay_[a-zA-Z0-9-]+$
Example:

"pay_1N3fKx2eZvKYlo2C0XjMr8pV"

​
object
enum<string>

Object type; always payment.

Available options:
payment
Example:

"payment"

​
amount
integer<int64>

The payment amount in minor units.

Example:

4999

​
currency
string

Three-letter ISO 4217 currency code.

Example:

"eur"

​
status
enum<string>

The current status of the payment.

  • pending -- The payment has been created but not yet completed (HPP flow).
  • succeeded -- The payment was successful.
  • failed -- The payment was declined or failed.
  • refunded -- The payment was refunded.
Available options:
pending,
succeeded,
failed,
refunded
Example:

"succeeded"

​
description
string | null

The description attached to the payment.

Example:

"Order #1234"

​
card
object

The masked card details. null for HPP payments that have not yet been completed.

​
customer
object

The customer associated with the payment.

​
metadata
object

Arbitrary key-value metadata attached to the payment.

Example:
{ "order_id": "ord_1234" }
​
decline_code
string | null

If the payment was declined, the decline code indicating the reason. See the decline codes reference for details.

Example:

null

​
decline_message
string | null

If the payment was declined, a human-readable message explaining why.

Example:

null

​
redirect_url
string<uri> | null

For HPP payments, the URL of the hosted payment page to redirect the customer to. null for direct API payments.

Example:

null

​
refunded_at
integer<int64> | null

Unix timestamp when the payment was refunded, or null if not refunded.

Example:

null

​
succeeded_at
integer<int64> | null

Unix timestamp when the payment succeeded, or null if not yet succeeded.

Example:

1719792000

​
failed_at
integer<int64> | null

Unix timestamp when the payment failed, or null if not failed.

Example:

null

​
created
integer<int64>

Unix timestamp when the payment was created.

Example:

1719792000

​
livemode
boolean

Whether this payment was created using a live API key (true) or a test API key (false).

Example:

false