Skip to main content
POST
Create a hosted payment page payment

Authorizations

​
Authorization
string
header
required

Use the secret API key for the intended merchant and mode as the Bearer token. Sandbox keys start with api_test_sk_. Send the key only from your server environment.

Headers

​
Idempotency-Key
string
required

A unique key to ensure one effective operation is processed only once. If the same key and an equivalent operation-specific effective request identity have already completed successfully, the original response is returned. A different identity returns 409 idempotency_key_reused. Non-2xx responses are not cached, so callers may retry after errors. No fixed retention period is promised by this contract.

For one-shot requests, such as creating a payment from a checkout button, a random UUIDv4 is fine. For requests tied to a specific business operation, such as refunding an order, a deterministic key is preferred so retries collapse correctly across processes.

Maximum string length: 255

Body

application/json
​
amount
integer<int64>
required

Payment amount in the currency's minor units. How many minor units make one major unit is set by the currency's ISO 4217 exponent, so the same integer means a different value in different currencies: 4999 is EUR 49.99 (exponent 2) but JPY 4999 (exponent 0). Do not assume two decimal places.

Required range: x >= 1
Example:

2500

​
currency
string
required

Three-letter ISO 4217 currency code supplied when creating a payment or payout. Accepted case-insensitively and with surrounding whitespace, then normalized to a canonical uppercase code before the operation is created.

A value that is not three letters is rejected with 400 parameter_invalid (param=currency); a well-formed code that Flowlix does not accept for that operation is rejected with 422 currency_not_supported. Neither creates a payment or payout. The available set is validated per request instead of being enumerated here, so enabling another currency is not a breaking contract change.

Required string length: 3 - 16
Pattern: ^\s*[A-Za-z]{3}\s*$
Example:

"EUR"

​
customer_ip_address
string
required

Shopper IPv4 or IPv6 address observed by the merchant during checkout. Send one literal address, not a hostname, port, or comma-separated proxy chain. Flowlix validates the complete IPv4 or IPv6 literal before registering the payment; the pattern is only an initial schema-level character and length guard.

Required string length: 3 - 45
Pattern: ^(((25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])|[0-9A-Fa-f:]*:[0-9A-Fa-f:.]*)$
Example:

"203.0.113.7"

​
return_url
string<uri>
required

Merchant URL where the customer returns after hosted payment completion or abandonment.

Example:

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

​
merchant_reference
integer<int64>

Optional merchant-side reconciliation reference. The value must contain exactly 10 decimal digits and does not provide idempotency by itself.

Required range: 1000000000 <= x <= 9999999999
Example:

1234567890

​
merchant_customer_id
string

Optional stable identifier for the shopper within the merchant account.

Required string length: 1 - 255
Example:

"customer_42"

​
billing_details
object

Optional payer contact and billing-address details used to prefill hosted payment pages.

​
description
string

Merchant-provided payment description.

Maximum string length: 500
Example:

"Order #5678"

Response

Hosted payment page payment accepted and a Payment object was created. REQUIRES_ACTION includes the hosted redirect; PENDING records an outcome that is not safe to resubmit; and FAILED records a terminal Payment result. A newly created HPP Payment does not return PROCESSING before the first customer redirect. Use GET /v1/payments/{id} as the source of truth for the final outcome.

A Payment represents one attempt to collect funds from the customer. Merchants can use merchant_reference to associate multiple payment attempts with the same order or checkout in their own systems.

​
id
string
required

Unique opaque identifier for a payment (pay_ prefix + random alphanumeric suffix).

Pattern: ^pay_[A-Za-z0-9]{24}$
Example:

"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"

​
amount
integer<int64>
required

Payment amount in the currency's minor units, per its ISO 4217 exponent: 4999 is EUR 49.99 but JPY 4999.

Required range: x >= 1
Example:

4999

​
currency
string
required

Canonical uppercase three-letter ISO 4217 currency code. Responses always return the original currency the payment was created in; a provider response never replaces it.

Required string length: 3
Pattern: ^[A-Z]{3}$
Example:

"EUR"

​
status
enum<string>
required

Current status of a payment attempt.

  • PENDING -- The payment was accepted by Flowlix and is awaiting provider submission or the next lifecycle decision.
  • REQUIRES_ACTION -- Customer action is required, such as completing 3D Secure authentication or a hosted payment page.
  • PROCESSING -- The payment is being processed by downstream payment systems.
  • SUCCEEDED -- The payment completed successfully.
  • FAILED -- The payment was declined or failed permanently.
  • EXPIRED -- The customer did not complete a required action before its expiry time.
Available options:
PENDING,
REQUIRES_ACTION,
PROCESSING,
SUCCEEDED,
FAILED,
EXPIRED
Example:

"SUCCEEDED"

​
integration_type
enum<string>
required

How the payment was collected. This is separate from the payment method instrument, such as card.

Available options:
DIRECT,
HOSTED_PAYMENT_PAGE
Example:

"DIRECT"

​
amount_refunded
integer<int64>
required

Total amount successfully refunded so far, in the payment currency's minor units, per its ISO 4217 exponent.

Required range: x >= 0
Example:

0

​
amount_refundable
integer<int64>
required

Remaining amount that can be refunded, in the payment currency's minor units, per its ISO 4217 exponent.

Required range: x >= 0
Example:

4999

​
created_at
integer<int64>
required

Unix timestamp when the payment was created.

Example:

1719792000

​
livemode
boolean
required

Always false for a Payment created in Sandbox.

Example:

false

​
merchant_reference
integer<int64> | null

Merchant-side reconciliation reference, if provided.

Required range: 1000000000 <= x <= 9999999999
Example:

1234567890

​
description
string | null

Merchant-provided payment description.

Example:

"Order #1234"

​
card
object | null

Masked card details, or null before card details are available.

​
billing_details
object | null

Billing details captured for the payment, if available.

​
failure_code
enum<string> | null

Machine-readable reason code when the payment reaches a terminal failed status.

Available options:
not_found,
processor_error,
processor_unavailable,
generic_decline,
do_not_honor,
issuer_declined,
insufficient_funds,
invalid_number,
invalid_expiry,
expired_card,
invalid_amount,
invalid_currency,
not_permitted,
cardholder_limit,
card_velocity_exceeded,
lost_card,
stolen_card,
suspect_fraud,
fraud_filter,
three_d_secure_failed,
three_d_secure_timeout,
three_d_secure_not_supported,
three_d_secure_error
Example:

"insufficient_funds"

​
failure_message
string | null

Human-readable explanation when the payment reaches a terminal failed status.

Example:

"The card has insufficient funds."

​
refunds
object[]

Refunds created for this payment, oldest first.

​
status_transitions
object

Timestamps for important payment status transitions.

​
next_action
object | null

Customer action required to continue the payment.