3DS Integration at Tuna#
Tuna has its own MPI (Merchant Plug-In) powered by Cybersource/Cardinal Cruise (Visa), which means you don't need to integrate with an external MPI provider. The 3DS authentication layer is handled transparently by Tuna's platform, and Cybersource is Tuna's 3DS provider under the hood — which is why several concepts in this guide (device data collection, step-up challenge, JWT) map directly to Cybersource Payer Authentication and Cardinal Cruise terminology.
3DS is activated on a per-merchant basis, according to each customer's risk and conversion strategy. The decision to use 3DS, and for which payment flows, is configured in Tuna Console's no-code flow editor. If you need help enabling or tuning 3DS for your account, contact your Account Manager or the Tuna Support team.
Not sure which integration mode to use?
If you use Tuna Checkout (hosted payment link or embedded), skip to the Tuna Checkout section — just configure your flow.
If you are on VTEX, skip to the VTEX section — it only takes one step. For all other platforms, choose one of the four direct integration modes below.
How 3DS works at Tuna#
A 3DS payment is composed of up to six steps. Steps 5–6 only happen when the issuer decides a challenge is required (the step-up flow); for frictionless authentications the payment finishes at step 4.
| # | Step | Who runs it | Endpoint / action |
|---|---|---|---|
| 1 | Create a session | Backend | POST /api/Token/NewSession |
| 2 | Tokenize the card with a 3DS code | Frontend | POST /api/Token/Generate |
| 3 | Device data collection | Frontend | Hidden iframe POST to Cardinal |
| 4 | Call Payment/Init | Backend | POST /api/Payment/Init |
| 5 | Render the challenge | Frontend | iframe POST to threeDSInfo.url |
| 6 | Confirm the result | Backend | POST /api/Payment/Status or webhooks |
Where does each field go?
The most common 3DS integration mistakes are sending the wrong field to the wrong endpoint. Use the 3DS field reference as your map — it tells you exactly where each value is produced and where it must be sent.
3DS field reference: what to send where#
Fields you create#
| Field | Where you create it | Where you send it | Description |
|---|---|---|---|
code (authentication reference code) | Your frontend — any random string of up to 50 characters | Token/Generate → AuthenticationInformation.Code, then the same value in Payment/Init → authenticationInformation.code | Correlates the 3DS setup made during tokenization with the payment. Must be identical in both calls. |
Fields returned by Token/Generate (3DS setup response)#
When you pass AuthenticationInformation.Code to Token/Generate, the response includes an authenticationInformation object with the Cardinal payer-auth setup data:
| Field | What it is | What to do with it |
|---|---|---|
authenticationInformation.accessToken | Cardinal JWT for device data collection | POST it as JWT to deviceDataCollectionUrl in a hidden iframe (step 3). Do not send it to Payment/Init. |
authenticationInformation.deviceDataCollectionUrl | Cardinal device data collection endpoint | Target of the hidden iframe form POST (step 3). |
authenticationInformation.referenceId | Cardinal/Cybersource reference ID of the payer-auth setup | Send to Payment/Init → authenticationInformation.referenceId. |
authenticationInformation.transactionId | Cardinal/Cybersource authentication transaction ID | Send to Payment/Init → authenticationInformation.transactionId. |
token | The card token | Send to Payment/Init → cardInfo.token. |
Fields your backend sends to Payment/Init#
| Field | Source | Notes |
|---|---|---|
authenticationInformation.code | The same code you sent to Token/Generate | Required |
authenticationInformation.referenceId | Token/Generate response | Required |
authenticationInformation.transactionId | Token/Generate response | Required |
cardInfo.token | Token/Generate response | Required |
frontData.* | Collected on the frontend, forwarded by your backend | Strongly recommended — see browser/device data |
Don't confuse the two transactionIds
Token/Generate returns authenticationInformation.transactionId (the 3DS authentication transaction). Payment/Init responses contain a different, unrelated transactionId (the acquirer transaction). Only the first one goes into Payment/Init's authenticationInformation.
Fields returned by Payment/Init — how the 3DS response differs#
A 3DS Payment/Init response has the same base structure as any other Init response (see the Init API reference), with one key difference: when the issuer requires a challenge, the method comes back pending with a threeDSInfo object that your frontend must use to render the challenge.
| Outcome | methods[].status | Extra data in response | What to do |
|---|---|---|---|
| Frictionless — authenticated without user interaction | Final status (e.g. 1 authorized, 2 captured) | None (no threeDSInfo) | Nothing — treat as a regular card payment |
| Challenge required (step-up) | P or 0 (pending) | threeDSInfo object | Render the challenge (step 5), then confirm via Status/webhooks |
| Authentication failed | 4 (not authorized) or similar error status | None | Ask the customer for another payment method |
The threeDSInfo object:
| Field | Description |
|---|---|
threeDSInfo.url | The ACS step-up URL. Render it inside an iframe by POSTing a form to it. |
threeDSInfo.token | JWT that must be POSTed to url as a form field named JWT. |
threeDSInfo.paRequest | Base64-encoded challenge request. Decode it to read challengeWindowSize and size the iframe correctly. |
threeDSInfo.provider | The MPI provider (e.g. CyberSource). |
Integration modes#
There are four integration approaches available in our official Postman collection. All of them follow the same six steps — they differ only in who performs each step:
| Mode | Who tokenizes? | Who calls Payment/Init? | Who renders the challenge? | Best for |
|---|---|---|---|---|
| 3DS with pure JS | Your frontend form | Your backend | Your frontend (manual iframe) | Full control, custom UI |
| 3DS using tuna.js for tokenization | tuna.js (frontend) | Your backend | Your frontend (manual iframe or open3dsModal) | Simplify PCI scope on frontend |
| 3DS using tuna.js for all interactions | tuna.js (frontend) | tuna.js (frontend) | tuna.js (automatic) | Fastest integration, full delegation |
| 3DS with manual tokenization | Your frontend (JS) | Your backend | Your frontend (manual iframe) | Direct control over card capture and tokenization |
Step 1 — Create a session (backend)#
The first step is always the same regardless of integration mode: create a Token session via your backend.
note
Always create sessions from your backend — never expose your apptoken on the frontend.
- Request
- Response
Set
Is3dsTest: truewhile testing in the sandbox. Remove it (or set tofalse) in production.
Store the sessionId — it is passed as SessionId to Token/Generate and as TokenSession to Payment/Init.
Step 2 — Tokenize the card with a 3DS code (frontend)#
Your frontend calls POST https://token.tunagateway.com/api/Token/Generate via JavaScript, passing the card data and an AuthenticationInformation.Code — a random string of up to 50 characters generated by you. Sending this code is what triggers the 3DS payer-auth setup at Cybersource; without it, no authenticationInformation is returned and the payment will not be authenticated.
PCI DSS requirement
Token/Generate — and any API that handles raw card data — must be called from the browser (frontend JS), not from your backend server, unless your company holds a PCI DSS Level 1 certification. This is why NewSession is always called from the backend (it only handles non-sensitive identifiers), while Token/Generate is called from the frontend.
- Request
- Response
Keep referenceId and transactionId together with your code — your backend needs all three for Payment/Init. The accessToken and deviceDataCollectionUrl are used in the next step and must not be sent to Payment/Init.
Step 3 — Device data collection (frontend)#
Before calling Payment/Init, the browser must run Cardinal's device data collection: a hidden iframe that POSTs the accessToken (as a field named JWT) to the deviceDataCollectionUrl. This lets the issuer fingerprint the device, which increases frictionless approval rates.
If you use tuna.js, the create3DSDataCollectionFrame method does all of this for you. See Cybersource's device data collection documentation for details on what is collected.
Step 4 — Call Payment/Init (backend)#
After device data collection completes, your frontend sends code, referenceId, transactionId, and the card token to your backend, which calls POST https://engine.tunagateway.com/api/Payment/Init:
- Credit (paymentMethodType 7)
- Debit (paymentMethodType 8)
See the full request/response examples (including a 3DS challenge response) in the Init API reference.
Payment method types
7(3DS 2.0 Credit) and8(3DS 2.0 Debit) make the 3DS requirement explicit — see the payment methods reference table. Regular types1/2withauthenticationInformationalso carry the authentication data; your flow configuration in Tuna Console determines how it is used.
Step 5 — Render the challenge (frontend)#
If the Payment/Init response has methods[].status of P or 0 and a threeDSInfo object, the issuer demands a challenge. Your backend forwards threeDSInfo to the frontend, which renders the challenge inside an iframe by POSTing the token as a form field named JWT to threeDSInfo.url — this is the Cardinal Cruise step-up iframe flow.
The iframe size should follow the challengeWindowSize encoded in threeDSInfo.paRequest (a base64 JSON payload):
challengeWindowSize | iframe size (W × H) |
|---|---|
01 | 250 × 400 |
02 | 390 × 400 |
03 | 500 × 600 |
04 | 600 × 400 |
05 | 100% × 100% (fullscreen) |
- tuna.js
- Pure JS
With tuna.js, call open3dsModal — it decodes paRequest, mounts a correctly sized modal with the challenge iframe, auto-submits the JWT form, and polls the payment status for you:
When you use
checkoutAndPay(Mode 3), tuna.js detects the challenge and callsopen3dsModalautomatically — the callback receiveswas3DSChallengeTriggered: trueand a3dsPollingEndwindow event fires when polling finishes.
Without tuna.js, build the iframe and form yourself:
The challenge result is sent to Tuna automatically by Cardinal — you don't need to capture it in the browser. Confirm the outcome in step 6.
Step 6 — Confirm the result (backend)#
After the challenge, Cardinal notifies Tuna and the payment resumes automatically. Confirm the final status by either:
- Polling the Payment Status API with the
paymentKeyandmethodIdfrom the Init response, or - Listening to payment webhooks.
If you use tuna.js's open3dsModal or checkoutAndPay, the polling is done for you.
Mode 1: 3DS with pure JS#
Your frontend handles card capture (using a custom form or any card entry UI) and runs all six steps manually, with your backend doing steps 1, 4, and 6.
How to use the Tuna sample form#
Open the Tuna-hosted sample for this mode:
- Enter the
sessionIdyou obtained in Step 1. - Fill in the card details (use a Cybersource test card — see test cards below).
- The form runs the 3DS device data collection and authentication challenge.
- On success it displays the
token,code,referenceId, andtransactionId. - Copy those values into your Postman
Init / CreditorInit / Debitrequest.
Follow steps 2–6 above using the Pure JS tabs.
Mode 2: 3DS using tuna.js for tokenization#
tuna.js handles card field rendering, tokenization (step 2), and device data collection (step 3) on the frontend. Your backend calls Payment/Init (step 4), and your frontend renders the challenge (step 5) with open3dsModal or a manual iframe.
How to use the Tuna sample form#
👉 tuna.js tokenization sample form
- Provide the
sessionIdfrom Step 1. - tuna.js renders the card fields and handles tokenization + device data collection transparently.
- On completion it returns the authentication data you need for
Payment/Init. - Pass those values to your backend, which calls
Payment/Initusing the same request structure as step 4 above.
Integration outline#
Add tuna.js to your page:
Initialize with the sessionId from your backend, tokenize, and run device data collection before handing off to your backend:
When your backend returns the Init response, render the challenge if needed as shown in step 5. See the full tuna.js documentation for all configuration options.
Mode 3: 3DS using tuna.js for all interactions#
tuna.js handles the complete flow: card entry, device data collection, the Payment/Init call, the challenge modal, and status polling — all from the browser. Your backend only needs to create the session.
note
Because tuna.js calls Payment/Init from the frontend in this mode, the session must be created with the full order data (PaymentAccount, partneruniqueid, amount/items) — not just customer data.
How to use the Tuna sample form#
👉 tuna.js full-flow sample form
- Your backend creates a
NewSessionincluding thePaymentAccountandpartneruniqueid. - Return the
sessionIdto the frontend. - tuna.js renders the checkout, performs 3DS, and submits the payment.
- Confirm the outcome via the callback, webhooks, or the Payment Status API.
Integration outline#
For the Postman collection, this mode only requires the NewSession call — tuna.js takes over from there.
Mode 4: 3DS with manual tokenization#
Identical to Mode 1 in flow, but you build the card capture form yourself and call Token/Generate directly via JavaScript (step 2) without any Tuna sample UI. This gives you full control over the card capture experience while keeping sensitive card data off your backend.
- Create the session on your backend (step 1).
- Tokenize with the 3DS code from your own form (step 2).
- Run device data collection (step 3).
- Call
Payment/Initfrom your backend (step 4). - Render the challenge when
threeDSInfois returned (step 5). - Confirm the result (step 6).
Providing browser/device data#
For all modes, passing frontData in Payment/Init is strongly recommended when using 3DS. It enables more accurate risk assessment and better frictionless rates:
| Field | Description |
|---|---|
userAgent | Browser User-Agent header |
ipAddress | Cardholder IP address |
acceptHeader | HTTP Accept header |
acceptLanguage | Browser language (IETF BCP47) |
colorDepth | Screen color depth in bits |
screenHeight / screenWidth | Screen dimensions in pixels |
timeDifference | UTC offset in minutes (e.g. -180 for BRT) |
javaEnabled | "Y" or "N" |
javaScriptEnabled | "Y" or "N" |
Mobile apps (Android & iOS)#
Tuna's Android SDK and iOS SDK handle card tokenization natively (steps 1–2). For the 3DS challenge on mobile you have two options:
- WebView-based challenge — run steps 3 and 5 inside a WebView using the same iframe/form technique shown above. This works with the standard flow and requires no additional SDK.
- Native challenge with the Cardinal Mobile SDK — for a fully native challenge UI, integrate the Cardinal Mobile SDK (available for Android and iOS), which is Cybersource/Cardinal's official mobile challenge renderer. Contact your Tuna Account Manager to coordinate the credentials required for this setup.
In both cases the backend-side steps (1, 4, and 6) are identical to the web flow.
VTEX#
For VTEX merchants, 3DS is enabled out of the box. All you need to do is install Tuna's VTEX IO app:
Install it from the VTEX App Store or via the VTEX IO CLI:
After installation, follow the standard Tuna VTEX plugin setup to configure your Gateway Affiliation and credentials. There is no additional 3DS configuration required — Tuna handles authentication automatically based on your flow settings in Tuna Console.
Headless & mobile apps on VTEX
Tuna has partnerships with the leading headless and mobile implementors in the VTEX ecosystem. 3DS is fully supported in storefronts built by Compra Rápida, Trinio, and Kobe. If your storefront runs on one of these platforms, contact your implementor or your Tuna Account Manager to enable 3DS.
Tuna Checkout#
If you use Tuna Checkout — whether as a hosted payment link shared externally or embedded in your page via iframe — 3DS is supported out of the box with no additional integration work.
All you need is the flow configuration in Tuna Console (no-code flow editor) to enable 3DS for the relevant payment methods. Tuna Checkout will handle the full authentication challenge flow automatically, including device data collection and the redirect/embedded challenge UI.
If you need help setting up your flow to include 3DS, contact your Account Manager or the Tuna Support team.
Cybersource test cards#
Tuna's MPI runs on Cybersource/Cardinal Cruise. Use the test cards below in the sandbox environment. They come from Cybersource's official Payer Authentication test cases.
How to use test cards#
- Replace every
Xin the card number with0(zero). - Use expiration month: January (01) and expiration year: current year + 3 (e.g., for 2026 use
01/2029). - Any CVV (e.g.,
123) works in the sandbox.
Visa (Card Type = 001) — most common for Brazilian merchants#
| Scenario | 3DS 2.2 Test Card | Enroll result | Validation result |
|---|---|---|---|
| 2.1 Frictionless — authentication successful | 4XXXXX XX XXXX 27X1 → 4000000000002701 | RC=100, VERes=Y, PARes=Y, ECI=05 (vbv) | No challenge required |
| 2.2 Frictionless — authentication unsuccessful | 4XXXXX XX XXXX 4574 → 4000000000004574 | RC=476, VERes=Y, PARes=N, ECI=07 | — |
| 2.3 Stand-in — attempted | 4XXXXX XX XXXX 2719 → 4000000000002719 | RC=100, VERes=Y, PARes=A, ECI=06 (vbv_attempted) | — |
| 2.4 Frictionless — authentication unavailable | 4XXXXX XX XXXX 2313 → 4000000000002313 | RC=100, VERes=Y, PARes=U | — |
| 2.5 Frictionless — authentication rejected | 4XXXXX XX XXXX 2537 → 4000000000002537 | RC=476, VERes=Y, PARes=R | — |
| 2.6 Authentication not available (system error) | 4XXXXX XX XXXX 299X → 4000000000002990 | RC=100, VERes=U | — |
| 2.7 Check enrollment error | 4XXXXX XX XXXX 2446 → 4000000000002446 | RC=100, VERes=U | — |
| 2.8 Timeout | 4XXXXX XX XXXX 2354 → 4000000000002354 | RC=100, VERes=U | — |
| 2.9 Step-up — challenge successful | 4XXXXX XX XXXX 25X3 → 4000000000002503 | RC=475, VERes=Y, PARes=C | RC=100, PARes=Y, ECI=05 (vbv) |
| 2.10 Step-up — challenge unsuccessful | 4XXXXX XX XXXX 4293 → 4000000000004293 | RC=475, VERes=Y, PARes=C | RC=476, PARes=N |
Mastercard (Card Type = 002)#
| Scenario | 3DS 2.2 Test Card | Enroll result |
|---|---|---|
| 2.1 Frictionless successful | 52XXXX XX XXX 2235 → 5200000000002235 | RC=100, VERes=Y, PARes=Y, ECI=02 (spa) |
| 2.2 Frictionless unsuccessful | 52XXXX XX XXXX 2276 → 5200000000002276 | RC=476, VERes=Y, PARes=N |
| 2.3 Stand-in attempted | 52XXXX XX XXXX 2482 → 5200000000002482 | RC=100, VERes=Y, PARes=A, ECI=01 (spa) |
| 2.9 Step-up successful | 52XXXX XX XXXX 2151 → 5200000000002151 | RC=475, PARes=C; validation RC=100, ECI=02 |
Elo (Card Type = 054)#
| Scenario | 3DS 2.2 Test Card | Enroll result | Validation result |
|---|---|---|---|
| 2.1 Frictionless — authentication successful | 65X529 XX XXXX 2XXX → 6505290000002000 | RC=100, VERes=Y, PARes=Y, ECI=05 (cs) | No challenge required |
| 2.2 Frictionless — authentication unsuccessful | 65X529 XX XXXX 2X18 → 6505290000002018 | RC=476, VERes=Y, PARes=N, ECI=07 | — |
| 2.3 Stand-in — attempted | 65X529 XX XXXX 2026 → 6505290000002026 | RC=100, VERes=Y, PARes=A, ECI=06 (cs_attempted) | — |
| 2.4 Frictionless — authentication unavailable | 65X529 XX XXXX 2X34 → 6505290000002034 | RC=100, VERes=Y, PARes=U | — |
| 2.5 Frictionless — authentication rejected | 65X529 XX XXXX 2X83 → 6505290000002083 | RC=476, VERes=Y, PARes=R | — |
| 2.9 Step-up — challenge successful | 65X529 XX XXXX 219X → 6505290000002190 | RC=475, VERes=Y, PARes=C | RC=100, PARes=Y, ECI=05 (cs) |
ECI value reference#
The ECI (E-Commerce Indicator) value in the enrollment/validation response indicates the authentication outcome:
| Network | Successful auth ECI | String value | Attempted ECI | Failed ECI |
|---|---|---|---|---|
| Visa | 05 | vbv | 06 (vbv_attempted) | 07 |
| Mastercard | 02 | spa | 01 | 00 |
| Amex | 05 | aesk | 06 (aesk_attempted) | 07 |
| Elo | 05 | cs | 06 (cs_attempted) | 07 |
| Discover | 05 | dipb | 06 (dipb_attempted) | 07 |
Interpreting test results#
PARes status | Meaning | Action |
|---|---|---|
Y | Authentication successful | Proceed with authorization — full liability shift |
A | Attempted (stand-in) | Proceed with authorization — partial liability shift |
U | Unavailable | Proceed with authorization — no liability shift |
N | Authentication failed | Do not proceed; ask for another payment method |
R | Authentication rejected | Do not proceed; ask for another payment method |
C | Challenge required (step-up) | Wait for challenge completion before proceeding |
Postman collection
Download the official collection at github.com/tuna-software/postman. The 3DS folder contains all four integration mode examples with pre-configured environments and test variables.
Cybersource & Cardinal documentation#
Cybersource is Tuna's 3DS provider. These external references are useful when you need the authoritative details of the underlying protocol:
| Reference | What it covers |
|---|---|
| Cybersource Payer Authentication (developer guide) | The full payer-auth lifecycle: setup, device data collection, enrollment, validation |
| Device data collection | What the hidden iframe in step 3 does and why it matters |
| Payer Authentication testing | Official test cases — source of the test cards above |
| Introduction to Payer Authentication | Cardinal Cruise concepts: browser-side integration, step-up, JWTs |
| Step-up iframe | How the challenge iframe works (the flow Tuna's integration is based on) |
| Cardinal Mobile SDK (Android/iOS) | Native mobile challenge rendering for apps |
| Cybersource API reference | Raw Cybersource REST API documentation |
note
You never call Cybersource/Cardinal APIs directly — Tuna does that for you. These links are provided so you can understand the underlying mechanics (JWTs, iframes, challenge window sizes) when debugging or customizing your challenge UI.