Skip to main content
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.
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 instead.

​
How it works

​
1. Create the payment

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:
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 and Operation failure codes.

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

​
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 relevant to your business.
  • Webhooks configured for asynchronous outcomes.