Create a Direct API payment

curl --request POST \
  --url https://api.flowlix.dev/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 4999,
  "currency": "EUR",
  "merchant_reference": "ord_1234",
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "314",
      "holder_name": "Jenny Rosen"
    }
  },
  "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"
}
'

{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 4999,
  "currency": "EUR",
  "status": "SUCCEEDED",
  "integration_type": "DIRECT",
  "amount_refunded": 0,
  "amount_refundable": 4999,
  "created_at": 1719792000,
  "livemode": false,
  "merchant_reference": "ord_1234",
  "description": "Order #1234",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "DE"
  },
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "line2": "Apartment 4B",
      "city": "Berlin",
      "state": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "metadata": {
    "order_id": "ord_1234"
  },
  "decline_code": "insufficient_funds",
  "decline_message": "The card has insufficient funds.",
  "hosted_payment_url": "https://pay.flowlix.dev/hpp/pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "refunds": [],
  "status_transitions": {
    "requires_action_at": null,
    "processing_at": 1719792002,
    "succeeded_at": 1719792042,
    "failed_at": null,
    "canceled_at": null,
    "expired_at": null
  },
  "next_action": {
    "redirect_url": "<string>"
  }
}

Payments

Create a Direct API payment

Creates a payment by charging a card directly. Submit card details under payment_method_data.card and payer billing data under billing_details.

The response is returned immediately with the payment attempt status. If the status is REQUIRES_ACTION, redirect the customer to next_action.redirect_url, then use GET /v1/payments/{id} or webhooks as the source of truth for the final result.

return_url is required for flows where 3D Secure authentication may be requested.

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

POST

payments

Create a Direct API payment

curl --request POST \
  --url https://api.flowlix.dev/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 4999,
  "currency": "EUR",
  "merchant_reference": "ord_1234",
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "314",
      "holder_name": "Jenny Rosen"
    }
  },
  "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"
}
'

{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 4999,
  "currency": "EUR",
  "status": "SUCCEEDED",
  "integration_type": "DIRECT",
  "amount_refunded": 0,
  "amount_refundable": 4999,
  "created_at": 1719792000,
  "livemode": false,
  "merchant_reference": "ord_1234",
  "description": "Order #1234",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "DE"
  },
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "line2": "Apartment 4B",
      "city": "Berlin",
      "state": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "metadata": {
    "order_id": "ord_1234"
  },
  "decline_code": "insufficient_funds",
  "decline_message": "The card has insufficient funds.",
  "hosted_payment_url": "https://pay.flowlix.dev/hpp/pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "refunds": [],
  "status_transitions": {
    "requires_action_at": null,
    "processing_at": 1719792002,
    "succeeded_at": 1719792042,
    "failed_at": null,
    "canceled_at": null,
    "expired_at": null
  },
  "next_action": {
    "redirect_url": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Use your secret API key as the Bearer token. Test mode keys start with api_test_sk_ and live mode keys start with api_live_sk_. Both modes use the same API host; the mode is determined by the key.

Authorization: Bearer api_test_sk_abc123def456

Headers

Idempotency-Key

string

required

A unique key to ensure the request is processed only once. If a request with the same idempotency key and the same body has already been processed successfully, the original response is returned. Non-2xx responses are not cached, so callers may retry after errors. Keys expire after 24 hours.

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 minor units.

Required range: x >= 1

Example:

4999

currency

enum<string>

required

Three-letter ISO 4217 currency code. Currently supported for card acquiring: EUR.

Available options:

EUR

Example:

"EUR"

payment_method_data

object

required

Show child attributes

billing_details

object

required

Show child attributes

return_url

string<uri>

required

URL where the customer returns after 3D Secure authentication.

Example:

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

merchant_reference

string

Merchant-side order or checkout reference for reconciliation. This field does not provide idempotency by itself.

Maximum string length: 255

Example:

"ord_1234"

description

string

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.redirect_url, while PROCESSING or PENDING should be followed with GET /v1/payments/{id} or webhooks.

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 minor units.

Required range: x >= 1

Example:

4999

currency

enum<string>

required

Three-letter ISO 4217 currency code. Currently supported for card acquiring: EUR.

Available options:

EUR

Example:

"EUR"

status

enum<string>

required

Current status of a payment attempt.

PENDING -- The payment was accepted by Flowlix and is waiting to be processed.
REQUIRES_ACTION -- Customer action is required, usually 3D Secure authentication.
PROCESSING -- The payment is being processed by downstream payment systems.
SUCCEEDED -- The payment completed successfully.
FAILED -- The payment was declined or failed permanently.
CANCELED -- The payment was canceled before completion.
EXPIRED -- The customer did not complete a required action before its expiry time.

Available options:

PENDING,

REQUIRES_ACTION,

PROCESSING,

SUCCEEDED,

FAILED,

CANCELED,

EXPIRED

Example:

"SUCCEEDED"

integration_type

enum<string>

required

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

Available options:

DIRECT,

HOSTED_PAYMENT_PAGE

Example:

"DIRECT"

amount_refunded

integer<int64>

required

Total amount successfully refunded so far, in minor units.

Required range: x >= 0

Example:

0

amount_refundable

integer<int64>

required

Remaining amount that can be refunded, in minor units.

Required range: x >= 0

Example:

4999

created_at

integer<int64>

required

Unix timestamp when the payment was created.

Example:

1719792000

livemode

boolean

required

Whether this payment was created using a live API key.

Example:

false

merchant_reference

string | null

Merchant-side order or checkout reference for reconciliation, if provided. This field does not provide idempotency by itself.

Maximum string length: 255

Example:

"ord_1234"

description

string | null

Merchant-provided payment description.

Example:

"Order #1234"

card

object

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

Show child attributes

billing_details

object

Billing details captured for the payment, if available.

Show child attributes

metadata

object

Merchant-provided metadata. Values may be any valid JSON value.

Show child attributes

Example:

{ "order_id": "ord_1234" }

decline_code

string | null

Machine-readable decline code when the payment fails.

Example:

"insufficient_funds"

decline_message

string | null

Human-readable decline explanation when available.

Example:

"The card has insufficient funds."

hosted_payment_url

string<uri> | null

URL of the hosted payment page for HPP payments.

Example:

"https://pay.flowlix.dev/hpp/pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"

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

Customer action required to continue the payment.

Show child attributes

List payments

Create a hosted payment page payment