Skip to main content
Many card payments need the shopper to confirm the payment with their bank: 3D Secure, which Strong Customer Authentication (SCA) requires in Europe. The card issuer decides when a challenge is needed. Kalixo.js and the hosted checkout run the challenge for you, so you do not integrate 3D Secure yourself.

How it works

  • When a payment needs authentication, its status becomes requires_action and the checkout shows the challenge: a passcode, an approval in the banking app, or a biometric check.
  • When the shopper passes, the payment moves to authorized. When they fail, it returns to requires_payment_method and the shopper can try again on the same session.
  • Authentication is per attempt. Each attempt counts towards the attempt limit of the session.

What you handle

Nothing specific to 3D Secure. Handle the normal outcomes:
  • In Kalixo.js, payment.processing means the outcome is still pending and payment.failed carries a message that is safe to show to the shopper.
  • Confirm every order on your server before you deliver it. See Fulfilment.
A passed challenge is not a captured payment. It only allows the authorisation. Fulfil after payment.captured (or payment.authorized with manual capture) and amount_mismatch: false.

Abandoned challenges

If the shopper closes the page during a challenge, the attempt stays open while the bank may still answer. A new attempt on the same session fails with payment_in_progress until the open attempt ends, after at most 30 minutes. To let the shopper pay sooner, create a new checkout session.

Decline codes

A failed authentication sets decline_code on last_payment_error and in payment.failed: See Errors for every decline code.

Testing

Pay with 4000 0000 0000 3220 to get a test challenge, then approve or decline it in the test dialog. See Testing. Simulated payments skip 3D Secure. Use the test card to test the challenge.