Direct API Quickstart

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.

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.

Prerequisites

Complete Authentication.
Use only the test data supplied for your current Sandbox account.
Collect the shopper’s literal IP address and an HTTPS return_url.

1. Create a Payment

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

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:

{
  "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.

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

4. Confirm the final status

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 and Operation failures.

Next steps

Create a Refund after a test Payment succeeds.
Submit and retrieve a Payout.
Receive Payment and Refund events.
Add complete API error handling.

Get started

Build with Flowlix

Handle failures

API reference

Direct API Quickstart

Prerequisites

1. Create a Payment

2. Inspect the create response

3. Complete a browser 3D Secure action when required

4. Confirm the final status

Safe retries

Next steps

​Prerequisites

​1. Create a Payment

​2. Inspect the create response

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

​4. Confirm the final status

​Safe retries

​Next steps

Prerequisites

1. Create a Payment

2. Inspect the create response

3. Complete a browser 3D Secure action when required

4. Confirm the final status

Safe retries

Next steps