Skip to main content
On this page

Submit the card payment once, present any returned 3DS next action, and verify the payment result on your backend. The authentication experience can collect browser signals, finish without a challenge, or ask the customer to authenticate with their bank.

Flow diagram
processedauthorizedStill pending orprocessingUnsuccessful1Submit payment once2Handle next_actionwhen returnedBrowser checks andoptional challenge3DEUNA completes orconfirms paymentprocessing4Verify originalorder on backend5Current paymentstatus6Apply fulfillmentpolicy7Follow agreedcapture policy8Keep unresolved andreconcile later9Show result andevaluate retryeligibility
DEUNAResult or outcomeReview or pending

Authentication can fail or be interrupted at any stage. The diagram shows the normal journey; the current payment status determines whether you wait, complete fulfillment, or offer recovery.

What your integration owns#

Your backend creates the payment and verifies its result. Your checkout presents the returned action and keeps the original order context. DEUNA coordinates browser checks, authentication, and any remaining authorization with the connected provider; the issuer controls the challenge and authentication decision.

Do not build your own sequence of provider authentication calls or assume that each step in the diagram requires a separate merchant API request. Use the returned action through the supported integration for your connection.

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 pending 3DS response can include the following fields. This example shows only the fields needed to continue the flow:

JSON
{
  "order": {
    "payment": {
      "data": {
        "status": "pending_3ds",
        "next_action": {
          "action": "authorization_3ds",
          "authorization_3ds": {
            "url_challenge": "https://api.deuna.io/transactions/next-action/NEXT_ACTION_ID"
          }
        }
      }
    }
  }
}

Use these fields as the source of truth:

FieldMeaningAction
order.payment.data.statuspending_3ds means the 3DS payment flow is unresolved.Keep fulfillment blocked and handle the returned action.
order.payment.data.next_action.actionIdentifies the required customer action.Handle authorization_3ds with the supported DEUNA SDK or returned challenge data.
order.payment.data.next_action.authorization_3ds.url_challengeDEUNA URL for the next authentication step, which can include browser checks before a challenge.Use the exact returned URL in the presentation mode supported for the connection.

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.

If a DEUNA Payment Widget already owns the payment journey, let that widget handle the returned action. Do not open a second Next Action instance for the same attempt. For a merchant-owned payment form, see the Next Action widget.

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.

Browser checks before a challenge

The returned experience can collect browser and device signals before the issuer decides whether to request a challenge. This step does not require the customer to enter a code or approve a payment. Keep the loading view and authentication surface available until the flow continues.

If browser data collection does not finish within its waiting period, the managed flow can continue with that result. This alone does not mean authentication failed or payment succeeded. Do not replace the returned action with a locally timed failure or start another purchase.

4. Wait for the final payment status#

Browser checks finishing, challenge completion, a return URL, and an SDK callback are signals to reconcile the original order. None is proof that funds were collected. Authentication may finish together with authorization, or DEUNA may still need to complete the payment afterward.

Use both:

  • configured, verified payment-status webhooks for backend updates; and
  • Get order when the customer returns or when your system needs to reconcile an uncertain result.
ResultMeaningFulfillment action
processedPurchase completed.Fulfill once your business checks pass.
authorizedFunds were authorized but not captured.Follow your capture strategy; do not treat as captured.
pending_3dsThe 3DS flow is still unresolved, with or without a visible challenge.Keep the current experience available; do not fulfill or restart automatically.
pending, processing, or authorizingThe payment is still in progress.Continue reconciliation; do not submit another purchase to finish 3DS.
denied, cancelled, or expiredThe payment did not complete.Show a recoverable outcome and start a new attempt only when appropriate.

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

5. Handle frictionless authentication#

Frictionless means the customer completes no issuer challenge. It can still require the returned browser experience to collect device signals and let payment processing continue. Your code must 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.

A successful payment without a challenge is not, by itself, proof that 3DS authentication succeeded. Use the reported authentication details when needed for support or liability analysis.

6. Timeouts and retries#

Browser data collection, challenge-view loading, issuer authentication, and payment processing have different waiting periods. A loading delay or a local timeout does not establish the payment result. Confirm the applicable authentication window for your connection during certification; do not hard-code one universal challenge duration.

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

After a closed view, network interruption, or timeout, retrieve the original order before offering another attempt. If the payment is still unresolved, show a pending result and continue reconciliation. If it is unsuccessful, apply the reported error and retry eligibility. A client-side close does not guarantee cancellation of the backend payment.

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.