3DS purchase flow

The 3DS integration is a payment-state workflow. Create the payment normally, react when DEUNA returns pending_3ds, present the returned next action, and wait for an authoritative final payment status.

1. Create the payment#

Use either supported card-payment pattern:

1. Create an order with Create order, then pay it with Create payment.
2. Use the single-request Create payment flow when it fits your integration.

Send complete shopper, billing, order, and device information. These signals help the issuer decide whether authentication can be frictionless.

2. Inspect the payment response#

A challenge-capable response follows this shape:

{
  "order": {
    "order_id": "75029759-4a64-42cd-b0b6-9f12777707b7",
    "status": "pending",
    "payment": {
      "data": {
        "id": "75029759-4a64-42cd-b0b6-9f12777707b7",
        "method_type": "credit_card",
        "status": "pending_3ds",
        "next_action": {
          "action": "authorization_3ds",
          "authorization_3ds": {
            "version": "2.2.0",
            "url_challenge": "https://api.deuna.io/transactions/next-action/...",
            "three_ds_flow_id": "0f5a8f52-7f95-4a1f-9ee8-e92946547ea9"
          }
        }
      }
    }
  }
}

Use these fields as the source of truth:

For compatibility, some integrations can also receive a top-level authorization_3ds object. New implementations should prefer next_action.

3. Present the next action#

Web SDK

Use initNextAction(...) when you want DEUNA to manage the supported modal, iframe, or redirect behavior. See the Web SDK reference.

Direct browser integration

If you handle the next action yourself:

1. Use the returned url_challenge; do not construct a 3DS URL.
2. Follow the configured presentation mode. Do not force an issuer page into an iframe when a top-level redirect is required.
3. Preserve your success, failure, and return URLs.
4. Treat a closed window, callback, or redirect as a signal to retrieve state—not as payment success.

Native apps

Use the supported DEUNA SDK or a secure system browser/web view. Configure the return/deep link and restore the payment context when the shopper returns to the app.

4. Wait for the final payment status#

While authentication is open, the payment remains pending_3ds. Authentication success only allows authorization to continue; it does not mean money moved.

Use both:

• verified DEUNA webhooks for asynchronous status changes; and
• Get order when the customer returns or when your system needs to reconcile an uncertain result.

See Payment Workflow & Statuses for every public payment state and transition.

5. Handle frictionless authentication#

Frictionless authentication might not return pending_3ds because the issuer can authenticate and let authorization continue in the same request. Your code must therefore support both outcomes:

• an immediate final or in-progress payment status; or
• pending_3ds plus an authorization_3ds next action.

Do not require the presence of a challenge URL to determine whether 3DS was evaluated.

6. Timeouts and retries#

Issuer challenge windows vary. DEUNA can keep a payment in pending_3ds for up to the configured authentication window; the current service safeguard does not exceed 10 minutes. After expiration, the payment transitions to a reported failure state and the shopper must begin a new payment attempt.

• Do not reuse an expired challenge URL.
• Do not create repeated payment attempts while the first payment remains unresolved.
• Use the final status and allow_retry/standardized error guidance when available before offering another attempt.
• If routing selects another compatible connection, let DEUNA decide whether an existing authentication result can be reused.

7. Interpret authentication details safely#

DEUNA Admin can display technical 3DS results such as the protocol version, flow type, ECI, authentication result, and network transaction identifiers. Use them for support, reconciliation, and dispute analysis.

Do not store or expose raw cryptograms, full authentication responses, or challenge HTML in merchant logs. A payment status—not an ECI or challenge completion event—controls fulfillment.