Create a Direct API payment

Creates a new payment by charging a card directly. The full card details are submitted in the request body. The payment is processed synchronously and the response includes the resulting status.

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

POST /v1/payments

Create a Direct API payment

cURL

curl --request POST \
  --url https://api.flowlix.eu/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 4999,
  "currency": "eur",
  "card": {
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2027,
    "cvc": "314",
    "holder_name": "Jenny Rosen"
  },
  "customer": {
    "email": "[e-mail]",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "country": "DE",
    "phone": "[phone]",
    "address": "Kurfuerstendamm 21",
    "city": "Berlin",
    "zip": "10719"
  },
  "description": "Order #1234",
  "metadata": {
    "order_id": "ord_1234",
    "sku": "WIDGET-XL"
  }
}
'

201

succeeded

{
  "id": "pay_1N3fKx2eZvKYlo2C0XjMr8pV",
  "object": "payment",
  "amount": 4999,
  "currency": "eur",
  "status": "succeeded",
  "description": "Order #1234",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "US"
  },
  "customer": {
    "email": "[e-mail]",
    "name": "Jenny Rosen"
  },
  "metadata": {
    "order_id": "ord_1234",
    "sku": "WIDGET-XL"
  },
  "decline_code": null,
  "decline_message": null,
  "redirect_url": null,
  "refunded_at": null,
  "succeeded_at": 1719792000,
  "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 (smallest currency unit). For EUR, 4999 means EUR 49.99. Must be a positive integer.

Required range: x >= 1

Example:

4999

currency · string · required

Three-letter ISO 4217 currency code in lowercase. Currently supported: eur, usd, gbp.

Required string length: 3

Pattern: ^[a-z]{3}$

Example:

"eur"

card · object · required

Show child attributes

customer · object

Show child attributes

description · string

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

Maximum string length: 500

Example:

"Order #1234"

metadata · object

A set of key-value pairs for storing additional information about the payment. Keys and values are strings. Maximum 50 keys, each key up to 40 characters, each value up to 500 characters.

Show child attributes

Example:

{
  "order_id": "ord_1234",
  "sku": "WIDGET-XL"
}

Response

201

application/json

Payment created successfully.

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.

Show child attributes

customer · object

The customer associated with the payment.

Show child attributes

metadata · object

Arbitrary key-value metadata attached to the payment.

Show child attributes

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