> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowlix.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct API

> Charge cards server-to-server from your own checkout UI

With the Direct API (host-to-host) integration, you collect card details in
your own checkout and submit them to Flowlix from your backend. You control
every pixel of the experience; Flowlix handles authorization, 3D Secure
orchestration, and settlement.

<Warning>
  **PCI DSS compliance is required.** With this integration, cardholder data
  (PAN, expiry, CVC) passes through your systems, which puts you in PCI DSS
  scope — typically SAQ D for merchants. You must provide a valid PCI DSS
  attestation of compliance before Direct API access is enabled on your live
  account. If you cannot or do not want to maintain PCI compliance, use the
  [Hosted Payment Page](/guides/hosted-payment-page) instead.
</Warning>

## How it works

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant M as Your server
    participant F as Flowlix

    C->>M: Submits card details on your checkout
    M->>F: POST /v1/payments (card + billing details)
    F-->>M: 201 Payment (SUCCEEDED, or REQUIRES_ACTION for 3DS, or PROCESSING)
    alt 3D Secure required
        M->>C: Redirect to next_action.redirect_url for next_action.reason
        C->>F: Completes 3D Secure challenge
        F->>C: Redirect to your return_url
    end
    M->>F: GET /v1/payments/{id} (or webhook)
    F-->>M: Final status (SUCCEEDED / FAILED)
```

## 1. Create the payment

```bash theme={null}
curl -X POST https://api.flowlix.dev/v1/payments \
  -H "Authorization: Bearer api_test_sk_abc123def456" \
  -H "Idempotency-Key: 7c0a1e9b-2f4d-4a6c-8b3e-5d9f0c2a4e6b" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4999,
    "currency": "EUR",
    "merchant_reference": 1234567890,
    "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",
      "address": {
        "line1": "Kurfuerstendamm 21",
        "city": "Berlin",
        "postal_code": "10719",
        "country": "DE"
      }
    },
    "description": "Order #1234",
    "return_url": "https://shop.example.com/3ds-return"
  }'
```

Field notes:

* **`payment_method_data.card`** — the raw card details collected on your
  checkout.
* **`billing_details`** — required; at minimum `email` and `address` with
  `line1`, `city`, `postal_code`, and `country`.
* **`merchant_reference`** is an optional reconciliation reference represented
  as an integer with exactly 10 digits (from `1000000000` to `9999999999`).
* **`return_url`** — required. If the issuer requests 3D Secure, this is where
  the customer lands after authentication.

## 2. Handle the response

The API responds `201 Created` with the payment attempt's current status.
Branch on `status`:

| `status`                 | What it means                 | What you do                                                                                       |
| ------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `SUCCEEDED`              | Charge approved synchronously | Fulfil the order                                                                                  |
| `REQUIRES_ACTION`        | Issuer requires 3D Secure     | Redirect the customer to `next_action.redirect_url` when `next_action.reason` is `three_d_secure` |
| `PROCESSING` / `PENDING` | Outcome not yet known         | Poll `GET /v1/payments/{id}` or wait for a webhook                                                |
| `FAILED`                 | Failed                        | Read `failure_code`, show a message, offer another payment method                                 |

<Note>
  A declined card is **not** an HTTP error. The request itself succeeded, so
  you receive `201` with `status: "FAILED"` and a machine-readable
  `failure_code` (for example `insufficient_funds`). HTTP `4xx` codes are
  reserved for problems with the request itself — bad fields, invalid keys,
  idempotency conflicts. See [Errors](/guides/errors) and
  [Operation failure codes](/guides/operation-failures).
</Note>

## 3. 3D Secure flow

When `status` is `REQUIRES_ACTION`:

1. Redirect the customer to `next_action.redirect_url` when
   `next_action.reason` is `three_d_secure`. Treat the URL as opaque: it may
   be a 3D Secure fingerprint collection step or a later authentication
   challenge.
2. Keep polling `GET /v1/payments/{id}` while the customer is in the browser
   flow. If the payment stays `REQUIRES_ACTION` and Flowlix returns a different
   `next_action.redirect_url`, redirect the customer to the new URL. If the URL
   is unchanged for the same browser session, do not redirect in a loop — show a
   pending state and keep polling.
3. After authentication — success or failure — the customer is redirected to
   your `return_url`.
4. Confirm the result with `GET /v1/payments/{id}`: `SUCCEEDED`, `FAILED`
   (for example `failure_code: "three_d_secure_failed"`), or `EXPIRED` if the
   customer never completed the challenge.

The same rule as for the hosted page applies: reaching `return_url` proves
nothing — the API status is the source of truth.

## Retries and duplicates

Always send an `Idempotency-Key` header. If your request times out or your
process crashes mid-call, retry with the **same key and the same body** — you
will get the original result back instead of charging the customer twice.
Details and edge cases: [Idempotency](/guides/idempotency).

## Going live checklist

* [ ] PCI DSS attestation submitted and approved.
* [ ] Card data never logged, stored, or sent to any system outside your PCI scope.
* [ ] `Idempotency-Key` sent on every create request, with retry-safe keys.
* [ ] 3D Secure redirect flow tested, including abandoned challenges.
* [ ] Failure handling covers the [operation failure codes](/guides/operation-failures) relevant to your business.
* [ ] Webhooks configured for asynchronous outcomes.