Skip to main content

​
Overview

3D Secure (3DS) adds an extra layer of authentication for card payments. When a card issuer requires 3DS, the Flowlix API returns a requires_action status with a redirect URL. Your integration must handle this status and redirect the customer to complete authentication. Flowlix supports 3DS 2.0 (the current standard mandated by PSD2/SCA in Europe). The decision on whether 3DS is needed is made by the card issuer — you don’t need to request it explicitly.

​
How it works

  1. Create a payment with return_url
  2. If 3DS is needed, the response includes status: "requires_action" and next_action
  3. Redirect the customer to next_action.redirect_url
  4. Customer completes authentication (SMS code, biometric, etc.)
  5. Customer is redirected back to your return_url
  6. Check the payment status — it will be succeeded or failed

​
Creating a payment with 3DS support

Include return_url in your payment request. All card and customer sub-fields are required by the API — see Direct API for the complete list. 
curl -X POST https://api.flowlix.dev/v1/payments \
  -H "Authorization: Bearer fl_test_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 5000,
    "currency": "eur",
    "return_url": "https://your-site.com/payment/complete",
    "card": {
      "number": "4635440000002223",
      "exp_month": 2,
      "exp_year": 2027,
      "cvc": "196",
      "holder_name": "Jenny Rosen"
    },
    "customer": {
      "email": "jenny.rosen@example.com",
      "first_name": "Jenny",
      "last_name": "Rosen",
      "country": "DE",
      "phone": "+491701234567",
      "address": "Kurfuerstendamm 21",
      "city": "Berlin",
      "zip": "10719"
    }
  }'

​
Handling the response

​
No 3DS required

{
  "id": "pay_01h9z8xm2c7q4r8s9t0v1w2x3y",
  "object": "payment",
  "status": "pending",
  "amount": 5000,
  "currency": "eur"
}
The payment is created and processed asynchronously. Poll GET /v1/payments/{id} until the status becomes succeeded or failed.

​
3DS required

{
  "id": "pay_01h9z8xm2c7q4r8s9t0v1w2x3y",
  "object": "payment",
  "status": "requires_action",
  "amount": 5000,
  "currency": "eur",
  "next_action": {
    "type": "redirect",
    "redirect_url": "https://acs.bank.com/3ds/..."
  }
}
Redirect the customer: 
if (payment.status === 'requires_action') {
  window.location.href = payment.next_action.redirect_url
}

​
After 3DS

The customer returns to your return_url. Check the payment status: 
curl https://api.flowlix.dev/v1/payments/pay_01h9z8xm2c7q4r8s9t0v1w2x3y \
  -H "Authorization: Bearer fl_test_sk_..."
The status will be succeeded, failed, or still pending (poll until resolved).

​
Timeout

If the customer doesn’t complete 3DS in time, the payment status changes to expired. Create a new payment to retry.

​
Test cards

CardBehavior
4635 4400 0000 2223Triggers 3DS challenge (sandbox)
4111 1111 1111 1111Approves without 3DS (sandbox)