3-D Secure (3DS2)

3-D Secure 2 (3DS2) is the card-network protocol that lets an issuer authenticate the cardholder before a payment is authorized. When authentication succeeds, liability for a fraudulent chargeback generally shifts from the merchant to the issuer, and where Strong Customer Authentication (SCA) mandates apply it is what makes a card payment acceptable at all. Authentication itself happens at the issuer's Access Control Server (ACS).

The reserved completion flow

This is the contracted behavior for a transaction in a 3DS challenge, documented so integrations are correct on the day challenge-issuing flows ship.

1. The transaction enters THREE_DS_PENDING — one of the 15 TransactionState values. It has a 15-minute TTL.

2. While THREE_DS_PENDING, TransactionResponse.three_ds is populated — and null in every other state, including after a completion. The ThreeDsChallenge required fields are challenge_url, acs_transaction_id, version, expires_at.

   {
     "transaction_id": "0190d8a1-2b3c-7d4e-9f12-7a8b9c0d1e2f",
     "state": "THREE_DS_PENDING",
     "three_ds": {
       "challenge_url": "https://acs.issuer.example/challenge/abc123",
       "acs_transaction_id": "…",
       "version": "2.2.0",
       "expires_at": "…"
     }
   }

   • challenge_url is issuer-hosted — it is the ACS page. It is not a Cresora page, and the platform does not host a payment or challenge domain for this flow.
   • version is the ThreeDsVersion enum: 2.1.0 or 2.2.0. Per spec: "Cresora always attempts 2.2.0 first and falls back to 2.1.0… 3DS 1.0 is deprecated by card networks and never produced by the platform."

3. The payer completes the challenge at the issuer. Your integration receives the opaque challenge_response token via the redirect from the ACS.

4. You call the completion endpoint with that token. Idempotency-Key is required, and merchant_id MUST match the parent transaction's merchant.

   curl -X POST "https://api.cresoracommerce.ai/api/v1/transactions/0190d8a1-2b3c-7d4e-9f12-7a8b9c0d1e2f/three-ds/complete" \
     -H "Authorization: Bearer csk_ab12cd34_xxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: idem_$(uuidgen)" \
     -d '{
       "challenge_response": "cres_3ds_pARf8UXu0Wm9qQPDfT4bP0Vk",
       "merchant_id": "0190d8a1-9f12-7d4e-2b3c-1e2f7a8b9c0d"
     }'

   challenge_response is opaque and at most 256 characters — pass through exactly what the ACS returned. A merchant_id that does not match the parent transaction's merchant returns 404 not_found — deliberately the same response as for a transaction that does not exist, so the endpoint cannot be used to probe which transaction ids exist under another merchant.

5. The response is a TransactionResponse at 200. A SALE parent transitions to CAPTURED; an AUTHORIZATION parent transitions to AUTHORIZED. A failed authentication transitions to THREE_DS_FAILED and carries three_ds_failure_reason.

Outcomes and failure reasons

three_ds_failure_reason is populated only on THREE_DS_FAILED. The exact values:

Replay and TTL semantics

• Completion is replay-safe by contract. Calling three-ds/complete against a transaction already CAPTURED, AUTHORIZED, or THREE_DS_FAILED returns the current state as 200 without re-calling the gateway — a successful no-op, so a duplicate ACS redirect or a client retry cannot double-charge.
• The TTL is 15 minutes. A sweep transitions expired challenges to THREE_DS_FAILED with three_ds_failure_reason of callback_timeout.
• A late completion against a swept transaction returns 200 with THREE_DS_FAILED — not 422. Read the state from the body, never from the status code alone.
• 422 means the transaction never reached 3DS at all — for example INITIATED, VOIDED, or REFUNDED.

Webhooks

Use these exact event names — platform prose elsewhere spells them two other ways, and the event enum above is authoritative.

Building tolerant handlers

No create path issues a step-up today, but the state and endpoint are contracted — so build for both:

• Treat THREE_DS_PENDING as a possible state on any transaction read. Do not model transaction state as a closed set that excludes it, and do not treat it as an error.
• Handle three_ds being null everywhere except THREE_DS_PENDING, including on the completion response itself. Never dereference it unconditionally.
• Read outcomes from state, not the HTTP status — 200 covers success, the replay no-op, and the late-completion failure.
• Send Idempotency-Key on the completion call and let a repeat return the current state, rather than keeping your own "already handled" bookkeeping.