Skip to content

Simplified Authentication Simulator

The Simplified Authentication Simulator is the default, recommended way to test 3D Secure during integration. Instead of hand-crafting simulated_flow metadata for every scenario, you simply send one of a small set of test card numbers and the gateway resolves a deterministic outcome — frictionless approval, an interactive approve/decline page, an auto-submitting form, or a processing decline.

This is the default integration option

New integrations should test 3DS with the test cards on this page. They cover the scenarios most integrations need (frictionless, redirect, form-submit, decline) without any metadata. The metadata-driven full 3DS simulator remains available for advanced cases that need to exercise the complete EMVCo fingerprint + challenge state machine.

How it works

When your merchant account is configured with the simplified-authentication-simulator authentication service (paired with the simplified-card-simulator card provider on the terminal), the gateway:

  1. Decrypts the submitted card number (PAN).
  2. Looks the PAN up in the test-card table below.
  3. Drives the matching outcome — and, for frictionless decline scenarios, stamps a processing code so the downstream authorization is declined too.

The outcome is delivered through the same result / action / redirect / form_submit response fields as a real 3DS transaction, so your integration code does not change between the simulator and production — only the card number does. See Response Handling for how to branch on those fields.

The redirect and form-submit outcomes complete against a gateway-controlled ACS-style page (the transaction id is carried in the URL path), so the flow always finalizes within your test environment — no external Directory Server or Access Control Server is involved.

sequenceDiagram
    participant Browser
    participant Server as Your Server
    participant Gateway as Payment Gateway

    Server ->> Gateway: POST /api/transactions/authorize (test card)
    Gateway ->> Gateway: Decrypt PAN → look up scenario

    alt Frictionless test card
        Gateway -->> Server: result (approved / declined)
    else Redirect test card
        Gateway -->> Server: redirect.url (gateway ACS page)
        Server -->> Browser: redirect browser to URL
        Browser ->> Gateway: Approve / Decline button
        Gateway -->> Browser: redirect to return_url
    else Form-submit test card
        Gateway -->> Server: form_submit (url + data)
        Server -->> Browser: auto-submit form
        Browser ->> Gateway: POST trans_status (Y / N)
        Gateway -->> Browser: redirect to return_url
    end

Test cards

A mapped card fully determines the outcome — no metadata is required. The same scenario is available on both a Visa and a Mastercard PAN.

Scenario Visa Mastercard What happens
Frictionless — approved 4000000000000002 5200000000000007 Authenticated without interaction (trans_status: Y); authorization is approved.
Redirect — interactive approve/decline 4000000000000010 5200000000000015 Response contains a redirect. The customer's browser is sent to a gateway-hosted ACS-style page with Approve and Decline buttons; the chosen result finalizes the transaction.
Form submit — authenticated 4000000000000028 5200000000000023 Response contains a form_submit that auto-posts trans_status: Y to the gateway completion endpoint. Authentication succeeds; authorization is approved.
Form submit — authentication declined 4000000000000036 5200000000000031 Response contains a form_submit that auto-posts trans_status: N. Authentication fails; the transaction is declined.
Frictionless authenticated, then processing decline 4000000000000044 5200000000000049 Authenticated frictionlessly (trans_status: Y), but the authorization step is declined with insufficient funds (TRX_STATUS_DECLINED_INSUFFICIENT_FUNDS).

Card numbers are matched after stripping whitespace

You may send the PAN with or without spaces. Only the digits are used for lookup, so 4000 0000 0000 0002 and 4000000000000002 resolve to the same scenario. The CVV, expiry, and cardholder name are not part of the lookup — use any valid-format values.

Handling each outcome

You handle the simulator's responses exactly as you would a real 3DS transaction.

Frictionless

The authorize response contains a populated result (and action, redirect, form_submit are all null). The transaction is already finalized — read its status from result or verify it via the Transaction Status API.

Redirect

{
  "result": null,
  "action": null,
  "redirect": {
    "transaction_id": "vvIVFmPuwYosePLsoDsW",
    "url": "https://<gateway>/simulator/simplified/three-ds/vvIVFmPuwYosePLsoDsW"
  },
  "form_submit": null
}

Redirect the customer's browser to redirect.url. The gateway serves an ACS-style page with Approve and Decline buttons:

  • Approve posts trans_status: Y → authentication succeeds.
  • Decline posts trans_status: N → authentication fails and the transaction is declined.

After the button is pressed the gateway finalizes the transaction and redirects the browser to your return_url. Verify the final outcome with the Transaction Status API or a webhook.

Form submit

{
  "result": null,
  "action": null,
  "redirect": null,
  "form_submit": {
    "transaction_id": "vvIVFmPuwYosePLsoDsW",
    "url": "https://<gateway>/simulator/simplified/three-ds/vvIVFmPuwYosePLsoDsW/authentication-completed",
    "data": {
      "trans_status": "Y"
    }
  }
}

Auto-submit a hidden form to form_submit.url with the fields from form_submit.data (see the submitHiddenForm helper). The form posts the predetermined trans_status to the gateway completion endpoint, which finalizes the transaction and redirects the browser to your return_url.

The form always posts to the gateway

The form-submit URL is always the gateway's own completion endpoint — it is never an external URL. This keeps the whole flow inside your test environment.

Cards not in the table (escape hatch)

When the submitted PAN is not in the test-card table (or cannot be decrypted), the simulator falls back to metadata, so you can still drive a redirect or form-submit with an arbitrary card:

Metadata key Effect
simulate_redirect Returns a redirect. The redirect always targets the gateway completion page (Approve/Decline).
simulate_form_submit Returns a form_submit that auto-posts to the gateway completion endpoint. Set {"trans_status":"N"} as the value to complete with a declined authentication; defaults to Y.
(neither present) 3DS is skipped (delegated) and the flow proceeds straight to authorization, where the simplified card simulator produces the result from the response_code metadata. 
{
  "metadata": {
    "simulate_form_submit": "{\"trans_status\":\"N\"}"
  }
}

Combine with the card simulator's response codes

Because an unmapped card skips straight to authorization, you can pair any non-table card with the card simulator metadata (e.g. response_code) to test authorization outcomes independently of the authentication leg.

Simplified vs. full simulator

Simplified Authentication Simulator Full 3DS simulator
Selected by Card number simulated_flow metadata
Fingerprint / method-URL step Skipped Configurable (incl. timeout scenarios)
Challenge state machine Single redirect / form-submit completion Full EMVCo fingerprint → challenge flow
Best for Everyday integration testing (default) Exercising the complete 3DS 2.x flow and edge cases