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

# Direct API Quickstart

> Submit a Sandbox card payment from your server and confirm the final Payment status

Direct API lets your checkout collect card details and send them from your
server to Flowlix. Every new Direct Payment goes through server-side
authentication. Your integration handles the initial request, a browser action
only when the Payment requires one, and retrieval of the authoritative result.

<Warning>
  Raw card number, expiry, and CVC enter your systems on this path. Use Direct
  API only from an approved PCI-compliant card-data environment. Never log or
  persist the request body.
</Warning>

## Prerequisites

* Complete [Authentication](/guides/authentication).
* Use only the test data supplied for your current [Sandbox account](/guides/testing).
* Collect the shopper's literal IP address and an HTTPS `return_url`.

## 1. Create a Payment

```bash theme={null}
curl -X POST "$FLOWLIX_BASE_URL/v1/payments" \
  -H "Authorization: Bearer $FLOWLIX_API_KEY" \
  -H "Idempotency-Key: order-1234567890-direct-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4999,
    "currency": "EUR",
    "merchant_reference": 1234567890,
    "customer_ip_address": "203.0.113.7",
    "payment_method_data": {
      "type": "card",
      "card": {
        "number": "4635440000002207",
        "exp_month": 12,
        "exp_year": 2027,
        "cvc": "314",
        "holder_name": "Jenny Rosen"
      }
    },
    "return_url": "https://shop.example/checkout/3ds-return"
  }'
```

The card number illustrates payload shape and belongs to Silverflow's published
3DS test range. It does not guarantee a successful, declined, or 3D Secure
outcome on every Sandbox account. Use the [test cards and 3DS cases](/guides/testing#test-cards)
for Silverflow processing, or test data supplied for your account's processor.

`amount`, `currency`, `payment_method_data`, `customer_ip_address`, and
`return_url` are required. Billing details and your customer or reconciliation
references are optional. See the
[complete request schema](/payments-api/payments/create-a-direct-api-payment).

## 2. Inspect the create response

The API returns `201 Created` with the current Payment state. Store its `id`
before taking further action.

| Status            | What to do now                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| `PROCESSING`      | Retrieve the Payment until it becomes terminal or requires a browser action.                     |
| `REQUIRES_ACTION` | Redirect the customer to `next_action.redirect_url`.                                             |
| `FAILED`          | Read `failure_code`; the request created a terminal Payment even though no funds were collected. |

A card decline is a Payment result, not an HTTP request error. This response
excerpt highlights the fields to inspect; the API reference shows full examples:

```json theme={null}
{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "status": "FAILED",
  "failure_code": "insufficient_funds",
  "failure_message": "The card has insufficient funds."
}
```

## 3. Complete a browser 3D Secure action when required

Server-side authentication is attempted for every new Direct Payment. A
browser redirect is required only when the returned Payment has
`status: REQUIRES_ACTION` and `next_action.reason: three_d_secure`.

1. Redirect the browser to the exact opaque `next_action.redirect_url`.
2. Retrieve the Payment while the browser action is in progress.
3. If a later response supplies a different redirect URL, use the latest one.
4. When the browser reaches `return_url`, retrieve the Payment again; do not
   treat the return itself as success.

## 4. Confirm the final status

```bash theme={null}
export PAYMENT_ID="pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"

curl "$FLOWLIX_BASE_URL/v1/payments/$PAYMENT_ID" \
  -H "Authorization: Bearer $FLOWLIX_API_KEY"
```

Continue while the status is `PENDING`, `REQUIRES_ACTION`, or `PROCESSING`.
Stop at `SUCCEEDED`, `FAILED`, or `EXPIRED`. Only `SUCCEEDED` authorizes order
fulfilment.

## Safe retries

* Persist the key and non-card fields, but never persist the raw card-data
  request body. Retry it only while the original body remains available inside
  your approved PCI handling boundary.
* Card fields are excluded from Direct Payment idempotency. The same key and
  unchanged non-card fields replay the original Payment even if different card
  fields are supplied; they do not attempt the different card.
* `idempotency_key_in_use` means wait briefly and retry with an equivalent
  effective request identity.
* `idempotency_key_reused` means the key was paired with different non-card
  fields; resend the original request or use a new key for a genuinely new
  Payment.
* A new card attempt always uses a new key.
* A terminal failed Payment is never resubmitted. A customer retry creates a
  new Payment with a new key.

See [Idempotency](/guides/idempotency) and
[Operation failures](/guides/operation-failures).

## Next steps

* [Create a Refund](/guides/refunds) after a test Payment succeeds.
* [Submit and retrieve a Payout](/guides/payouts).
* [Receive Payment and Refund events](/guides/webhooks).
* Add complete [API error handling](/guides/errors).