curl --request POST \
  --url https://api.flowlix.eu/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 4999,
  "currency": "EUR",
  "merchant_reference": 1234567890,
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "4635440000002207",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "314",
      "holder_name": "Jenny Rosen"
    }
  },
  "customer_ip_address": "203.0.113.7",
  "merchant_customer_id": "cust_opaque_42",
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "city": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "description": "Order #1234",
  "return_url": "https://merchant.example/payments/return"
}
'

{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 4999,
  "currency": "EUR",
  "status": "PROCESSING",
  "integration_type": "DIRECT",
  "merchant_reference": 1234567890,
  "description": "Order #1234",
  "payment_method": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "2207",
      "exp_month": 12,
      "exp_year": 2027,
      "cardholder_name": "Jenny Rosen"
    }
  },
  "amount_refunded": 0,
  "amount_refundable": 0,
  "refunds": [],
  "status_transitions": {
    "processing_at": 1719792002
  },
  "created_at": 1719792000,
  "livemode": false
}

Payments

Create a Direct API payment

Creates a payment using exactly one merchant-facing payment method. Submit ordinary card details under payment_method_data.card, or submit a prepared decrypted Apple Pay or Google Pay credential under its wallet object. Google Pay PAN_ONLY also requires browser_information. The shopper IP belongs in customer_ip_address; optional payer identity or billing data may be supplied when the merchant has it.

Apple Pay and Google Pay are Experimental: their support and this guidance are still being refined and are not final, and the wallet fields and validation described here can change. Ordinary card requests are not affected. See wallet contract availability.

The card number illustrates payload shape only. It does not guarantee a successful, declined, or 3D Secure outcome. In Sandbox the outcome comes from the amount, not from the card: see Sandbox testing.

Every new Direct Payment goes through server-side authentication. The response contains the payment attempt status after bounded eligible provider retries. Exhausted preparation before execution can return FAILED with processor_unavailable or processor_error, not an issuer decline. Uncertain execution is reconciled against the existing order; technical read failures alone leave the payment nonterminal. If the status is REQUIRES_ACTION, a browser action is required: redirect the customer to next_action.redirect_url for the next_action.reason customer action, then use GET /v1/payments/{id} as the source of truth for the final result. Required-action redirect URLs are opaque and may change while the payment is still REQUIRES_ACTION; redirect the customer again only when the latest next_action.redirect_url differs from the one that browser already visited.

return_url is required. Use an HTTPS URL; reaching it never proves payment success.

New Direct Payments require one of the supported payment currencies. A well-formed unsupported currency returns 422 currency_not_supported without creating a Payment. Existing Payments in other currencies remain readable.

Use the Idempotency-Key header to safely retry requests without creating duplicate charges.

POST

payments

curl --request POST \
  --url https://api.flowlix.eu/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 4999,
  "currency": "EUR",
  "merchant_reference": 1234567890,
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "4635440000002207",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "314",
      "holder_name": "Jenny Rosen"
    }
  },
  "customer_ip_address": "203.0.113.7",
  "merchant_customer_id": "cust_opaque_42",
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "city": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "description": "Order #1234",
  "return_url": "https://merchant.example/payments/return"
}
'

{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 4999,
  "currency": "EUR",
  "status": "PROCESSING",
  "integration_type": "DIRECT",
  "merchant_reference": 1234567890,
  "description": "Order #1234",
  "payment_method": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "2207",
      "exp_month": 12,
      "exp_year": 2027,
      "cardholder_name": "Jenny Rosen"
    }
  },
  "amount_refunded": 0,
  "amount_refundable": 0,
  "refunds": [],
  "status_transitions": {
    "processing_at": 1719792002
  },
  "created_at": 1719792000,
  "livemode": false
}

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.

Authorization: Bearer api_test_sk_abc123def456

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, using its ISO 4217 exponent. For example, 4999 is EUR 49.99 (exponent 2).

Required range: x >= 1

Example:

4999

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. For new Payment eligibility, see the supported payment currencies; Payout eligibility is independent.

Required string length: 3 - 16

Pattern: ^\s*[A-Za-z]{3}\s*$

Example:

"EUR"

payment_method_data

object

required

Select exactly one payment method. Card, decrypted Apple Pay, and decrypted Google Pay are supported by this direct-payment contract. The selected method determines which credential fields are accepted; credentials are never inferred from another method's fields.

The apple_pay and google_pay methods are Experimental: their support and this guidance are still being refined and are not final, and their fields and validation can change. The card method is not affected. See wallet contract availability.

Option 1
Option 2
Option 3

Show child attributes

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"

merchant_customer_id

string

required

Stable merchant-scoped non-PII opaque identity. Reuse it for the same logical customer or recognized guest. Do not send an email, phone number, login, name, payment ID, order ID, attempt ID, fresh per-payment UUID, or any other fresh per-payment value. Case and whitespace are significant. The value must contain 1-255 Unicode scalar values, must be nonblank, and U+0000 is forbidden.

Required string length: 1 - 255

Example:

"cust_opaque_42"

return_url

string<uri>

required

Send the HTTPS URL where the customer returns after 3D Secure authentication.

Example:

"https://shop.example.com/3ds-return"

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

browser_information

object

Actual payer-browser information, not the caller server's environment. Required for the Experimental Google Pay PAN_ONLY method and optional for other direct methods. When supplied, it is sent as transient provider authentication and risk context; it does not prove that a challenge occurred or that a Payment succeeded. The existing customer_ip_address supplies the payer browser IP, so no second browser-IP field is accepted. When supplied, all nine fields are required; do not fabricate missing browser values.

Show child attributes

billing_details

object

Optional payer contact and billing-address details for a direct payment.

Show child attributes

description

string | null

Merchant-provided payment description.

Maximum string length: 500

Example:

"Order #1234"

Response

Payment accepted and a Payment object was created. Check status before treating the payment as complete; REQUIRES_ACTION includes next_action.reason and next_action.redirect_url, while PENDING or PROCESSING should be followed with GET /v1/payments/{id}. Reconciliation can already have confirmed a terminal result. FAILED is a terminal Payment result, not an HTTP request error.

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.

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"

payment_method

object | null

required

Known submitted direct method or authoritative selected hosted-page method. Null means unknown, not card; the field is always present. This does not imply success. No wallet credentials or authentication payload is returned.

The apple_pay and google_pay values are Experimental: wallet support and this guidance are still being refined and are not final. See wallet contract availability.

Show child attributes

Example:

{
  "type": "apple_pay",
  "card": {
    "brand": "visa",
    "last4": "2207",
    "exp_month": 12,
    "exp_year": 2028
  }
}

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. This is 0 unless status is SUCCEEDED, because no amount was captured on a payment that has not succeeded. For a SUCCEEDED payment it is the payment amount less anything already refunded or reserved for a refund in flight.

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"

billing_details

object | null

Billing details captured for the payment, if available.

Show child attributes

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.

Show child attributes

status_transitions

object

Timestamps for important payment status transitions.

Show child attributes

next_action

object | null

Customer action required to continue the payment.

Show child attributes

⌘I

Get started

Build with Flowlix

Handle failures

API reference

Create a Direct API payment

Authorizations

Headers

Body

Response