Adding 3DS authentication

This guide explains how to add 3DS Authentication to your native mobile integration. By using the native 3DS flow, you handle the “Identify” and “Challenge” phases directly within your app, providing a seamless experience that avoids browser redirects and improves conversion rates.

Prerequisites

This guide explains how to add 3DS authentication to your native mobile integration. Before you begin, ensure you have:

The Gr4vy SDK installed in your project (see native vaulting guide for installation steps).
Your backend set up to create checkout sessions and process transactions.

Native mobile 3DS requires merchant account-level 3DS configuration to be enabled and properly configured. This feature is currently in beta. Please contact the support team to enable it for your account, then follow the 3DS Setup guide to configure it before proceeding with this integration.

How it works

The native 3DS implementation automatically handles all device fingerprinting requirements, including collecting the device’s IP address, user agent, location data, and other authentication metadata needed for 3-D Secure compliance. This ensures full compliance with 3-D Secure specifications without requiring manual fingerprint collection on your side.

Limitations & Considerations

When you use native 3DS with these native SDKs, it is important to pass the transaction context (for example, metadata, merchant_initiated, or cart_items) when you create the Checkout Session. As native 3DS runs before transaction creation, so this context must already be present at session creation time to find the right 3DS profile, as well as take into consideration any flow rules. Additionally, it’s important to note that the system runs 3DS Flow rules at the time of the enrollment check, which is run at the time of submitting Secure Fields. Currently, this Flow rule check doesn’t support anti-fraud checks as these are currently tied to a transactions, though there are plans to add this in the near future.

Implementation

1. Create a Checkout Session

First, create a checkout session on your backend with the transaction amount and currency. This session stores the authenticated card data for 3DS processing.

using Gr4vy;
using Gr4vy.Models.Components;

var sdk = new Gr4vySDK(
    merchantAccountId: "default",
    bearerAuth: "<YOUR_BEARER_TOKEN_HERE>"
);

var checkoutSession = await sdk.CheckoutSessions.CreateAsync(
    checkoutSessionCreate: new CheckoutSessionCreate() {
        Amount = 1800,
        Currency = "EUR",
    }
);

// Return the session ID to your mobile app
var sessionId = checkoutSession.CheckoutSession.Id;

package main

import(
	"context"
	gr4vygo "github.com/gr4vy/gr4vy-go"
	"os"
	"github.com/gr4vy/gr4vy-go/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := gr4vygo.New(
        gr4vygo.WithMerchantAccountID("default"),
        gr4vygo.WithSecurity(os.Getenv("GR4VY_BEARER_AUTH")),
    )

    checkoutSession, err := s.CheckoutSessions.Create(ctx, &components.CheckoutSessionCreate{
        Amount: gr4vygo.Int64(1800),
        Currency: gr4vygo.String("EUR"),
    })
    if err != nil {
        log.Fatal(err)
    }
    if checkoutSession != nil {
        // Return the session ID to your mobile app
        log.Printf("Session ID: %s", checkoutSession.CheckoutSession.ID)
    }
}

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.components.CheckoutSessionCreate;
import com.gr4vy.sdk.models.operations.CreateCheckoutSessionResponse;
import java.lang.Exception;

public class Application {
    public static void main(String[] args) throws Exception {
        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth("<YOUR_BEARER_TOKEN_HERE>")
            .build();

        CreateCheckoutSessionResponse res = sdk.checkoutSessions().create(
            CheckoutSessionCreate.builder()
                .amount(1800L)
                .currency("EUR")
                .build()
        ).call();

        if (res.checkoutSession().isPresent()) {
            // Return the session ID to your mobile app
            String sessionId = res.checkoutSession().get().id();
            System.out.println("Session ID: " + sessionId);
        }
    }
}

declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;

$sdk = Gr4vy\SDK::builder()
    ->setMerchantAccountId('default')
    ->setSecurity('<YOUR_BEARER_TOKEN_HERE>')
    ->build();

$response = $sdk->checkoutSessions->create(
    checkoutSessionCreate: new Gr4vy\CheckoutSessionCreate(
        amount: 1800,
        currency: 'EUR',
        country: 'DE'
    )
);

if ($response->checkoutSession !== null) {
    // Return the session ID to your mobile app
    echo "Session ID: " . $response->checkoutSession->id;
}

from gr4vy import Gr4vy
import os

with Gr4vy(
    merchant_account_id="default",
    bearer_auth=os.getenv("GR4VY_BEARER_AUTH", ""),
) as g_client:
    # Create a checkout session with amount and currency
    checkout_session = g_client.checkout_sessions.create(
        checkout_session_create={
            "amount": 1800,
            "currency": "EUR",
        }
    )
    # Return the session ID to your mobile app
    print(checkout_session.id)

import { Gr4vy } from '@gr4vy/sdk'

const gr4vy = new Gr4vy({
    gr4vyId: 'your-gr4vy-id',
    privateKey: 'your-private-key',
    environment: 'sandbox',
})

async function createCheckoutSession() {
    const checkoutSession = await gr4vy.checkoutSessions.create({
        amount: 1800,
        currency: 'EUR',
    })
    // Return the session ID to your mobile app
    console.log(checkoutSession.id)
}

createCheckoutSession()

Pass this session ID to your mobile app so it can be used in the next step.

2. Update SDK logic

/// Create card data
let cardData = Gr4vyCardData(
    paymentMethod: .card(CardPaymentMethod(
        number: "4111111111111111",
        expirationDate: "12/25",
        securityCode: "123"
    ))
)

// Tokenize with 3DS authentication (async/await)
do {
    let result = try await gr4vy.tokenize(
        checkoutSessionId: "session_123",
        cardData: cardData,
        sdkMaxTimeoutMinutes: 5,
        authenticate: true
    )

    if result.tokenized {
        print("Payment method tokenized successfully")

        // Check authentication details
        if let auth = result.authentication {
            print("3DS attempted: \(auth.attempted)")
            print("Authentication type: \(auth.type ?? "N/A")")
            print("Transaction status: \(auth.transactionStatus ?? "N/A")")

            if auth.hasCancelled {
                print("User cancelled authentication")
            }
            if auth.hasTimedOut {
                print("Authentication timed out")
            }
        }
    }
} catch {
    print("Error tokenizing payment method: \(error)")
}

// With explicit view controller (async/await)
do {
    let result = try await gr4vy.tokenize(
        checkoutSessionId: "session_123",
        cardData: cardData,
        viewController: self, // Explicitly provide the presenting view controller
        sdkMaxTimeoutMinutes: 5,
        authenticate: true
    )
    print("Tokenization complete: \(result.tokenized)")
} catch {
    print("Error: \(error)")
}

// Completion handler variant
gr4vy.tokenize(
    checkoutSessionId: "session_123",
    cardData: cardData,
    sdkMaxTimeoutMinutes: 5,
    authenticate: true
) { result in
    switch result {
    case .success(let tokenizeResult):
        if tokenizeResult.tokenized {
            print("Payment method tokenized successfully")
            if let auth = tokenizeResult.authentication {
                print("Transaction status: \(auth.transactionStatus ?? "N/A")")
            }
        }
    case .failure(let error):
        print("Error tokenizing payment method: \(error)")
    }
}

// Create card data
val cardData = Gr4vyCheckoutSessionRequest(
    paymentMethod = Gr4vyPaymentMethod.Card(
        number = "4111111111111111",
        expirationDate = "12/25",
        securityCode = "123"
    )
)

// Tokenize with 3DS authentication (suspend function)
lifecycleScope.launch {
    try {
        val result = gr4vy.tokenize(
            checkoutSessionId = "session_123",
            cardData = cardData,
            activity = this@PaymentActivity,
            sdkMaxTimeoutMinutes = 5,
            authenticate = true
        )

        if (result.tokenized) {
            println("Payment method tokenized successfully")

            // Check authentication details
            result.authentication?.let { auth ->
                println("3DS attempted: ${auth.attempted}")
                println("Authentication type: ${auth.type}")
                println("Transaction status: ${auth.transactionStatus}")

                if (auth.hasCancelled) {
                    println("User cancelled authentication")
                }
                if (auth.hasTimedOut) {
                    println("Authentication timed out")
                }
            }
        }
    } catch (error: Gr4vyError) {
        println("Error tokenizing payment method: $error")
    }
}

// Callback version
gr4vy.tokenize(
    checkoutSessionId = "session_123",
    cardData = cardData,
    activity = this@PaymentActivity,
    sdkMaxTimeoutMinutes = 5,
    authenticate = true
) { result ->
    when {
        result.isSuccess -> {
            val tokenizeResult = result.getOrNull()
            if (tokenizeResult?.tokenized == true) {
                println("Payment method tokenized successfully")
                tokenizeResult.authentication?.let { auth ->
                    println("Transaction status: ${auth.transactionStatus}")
                }
            }
        }
        result.isFailure -> {
            println("Error tokenizing payment method: ${result.exceptionOrNull()}")
        }
    }
}

3. Backend Authorization

Once the SDK returns a successful result, the 3DS verification data is securely stored within the Checkout Session. When your app notifies your backend, create the transaction by referencing the session ID in the payment_method object. The system automatically detects the 3DS data and ensures it is passed to your payment processor to satisfy SCA requirements.

POST /transactions
{

    "amount": 1800,
    "currency": "EUR",
    "country": "DE",
    "intent": "capture",
    "payment_method": {
        "method": "checkout-session",
        "id": "[checkout-session-id]"
    },
    ...
}

Handling failed authentication

If a customer fails or cancels their 3DS authentication, you have the option to still process the payment using the vaulted card data. This is useful for scenarios where:

The customer wants to retry with a different payment method later
You want to reduce friction by allowing offline card storage
Your business model supports processing payments without 3DS authentication (subject to regional regulations and processor rules)

Theming

When a 3DS challenge is required, the Gr4vy SDK presents a native interface provided by the card issuer. You can customize the appearance of these screens to ensure they match your app’s branding and provide a consistent user experience. Customization is handled via a uiCustomization object passed during the SDK initialization. This allows you to define colors, fonts, and button styles that are applied to the 3DS challenge modals.

Text: Colors and font sizes for headings, body text, and input fields.
Buttons: Background colors, text colors, and corner radii for “Continue” and “Cancel” actions.
Navigation Bar: Background and title colors for the header.
Input Fields: Border colors and focus states.

// Create toolbar customization
let toolbar = Gr4vyThreeDSToolbarCustomization(
    textColorHex: "#FFFFFF",
    backgroundColorHex: "#007AFF",
    headerText: "Secure Verification",
    buttonText: "Cancel"
)

// Create button customizations
let submitButton = Gr4vyThreeDSButtonCustomization(
    textFontSize: 16,
    textColorHex: "#FFFFFF",
    backgroundColorHex: "#007AFF",
    cornerRadius: 8
)

let cancelButton = Gr4vyThreeDSButtonCustomization(
    textFontSize: 16,
    textColorHex: "#007AFF",
    backgroundColorHex: "#F0F0F0",
    cornerRadius: 8
)

// Create label customization
let label = Gr4vyThreeDSLabelCustomization(
    textFontSize: 14,
    textColorHex: "#333333",
    headingTextFontSize: 18,
    headingTextColorHex: "#000000"
)

// Create text box customization
let textBox = Gr4vyThreeDSTextBoxCustomization(
    textFontSize: 16,
    textColorHex: "#000000",
    borderWidth: 1,
    borderColorHex: "#CCCCCC",
    cornerRadius: 4
)

// Combine into UI customization
let uiCustomization = Gr4vyThreeDSUiCustomization(
    label: label,
    toolbar: toolbar,
    textBox: textBox,
    buttons: [
        .submit: submitButton,
        .cancel: cancelButton
    ]
)

// Use with tokenization
let result = try await gr4vy.tokenize(
    checkoutSessionId: "session_123",
    cardData: cardData,
    authenticate: true,
    uiCustomization: Gr4vyThreeDSUiCustomizationMap(default: uiCustomization)
)

// Create toolbar customization
val toolbar = Gr4vyThreeDSToolbarCustomization(
    textFontName = "sans-serif-medium",
    textFontSize = 17,
    textColorHex = "#FFFFFF",
    backgroundColorHex = "#007AFF",
    headerText = "Secure Verification",
    buttonText = "Cancel"
)

// Create button customizations
val submitButton = Gr4vyThreeDSButtonCustomization(
    textFontSize = 16,
    textColorHex = "#FFFFFF",
    backgroundColorHex = "#007AFF",
    cornerRadius = 8
)

val cancelButton = Gr4vyThreeDSButtonCustomization(
    textFontSize = 16,
    textColorHex = "#007AFF",
    backgroundColorHex = "#F0F0F0",
    cornerRadius = 8
)

// Create label customization
val label = Gr4vyThreeDSLabelCustomization(
    textFontSize = 14,
    textColorHex = "#333333",
    headingTextFontSize = 18,
    headingTextColorHex = "#000000"
)

// Create text box customization
val textBox = Gr4vyThreeDSTextBoxCustomization(
    textFontSize = 16,
    textColorHex = "#000000",
    borderWidth = 1,
    borderColorHex = "#CCCCCC",
    cornerRadius = 4
)

// Combine into UI customization
val uiCustomization = Gr4vyThreeDSUiCustomization(
    label = label,
    toolbar = toolbar,
    textBox = textBox,
    buttons = mapOf(
        Gr4vyThreeDSButtonType.SUBMIT to submitButton,
        Gr4vyThreeDSButtonType.CANCEL to cancelButton
    )
)

// Use with tokenization
val result = gr4vy.tokenize(
    checkoutSessionId = "session_123",
    cardData = cardData,
    activity = this@PaymentActivity,
    authenticate = true,
    uiCustomization = Gr4vyThreeDSUiCustomizationMap(default = uiCustomization)
)

All color values should be provided as hexadecimal strings (for example, #007AFF).

Testing and validation

To test your implementation, use the 3DS Test Cards defined here in your sandbox environment.

Frictionless Flow: Use a card that is configured to skip the challenge phase. The SDK can return success immediately after the authentication call.
Challenge Flow: Use a card that requires an SMS or Biometric challenge. The SDK can automatically present the native modal for you to complete.

Use these card numbers and scenarios to test your native 3DS implementation in the Gr4vy Sandbox environment. These cards allow you to simulate various outcomes, including frictionless authentication, mandatory challenges, and specific failure states.

Testing scenarios

Visa

Card Number	Expected 3DS Outcome
`4000 0000 0000 0010`	Frictionless Success: Authenticated without user interaction.
`4000 0000 0000 0028`	Challenge Required: Triggers a native 3DS challenge UI.
`4000 0000 0000 0044`	Authentication Failed: Simulates a “Not Authenticated” result.
`4000 0000 0000 1042`	Rejected: The authentication request was explicitly rejected.

Mastercard

Card Number	Expected 3DS Outcome
`5100 0000 0000 0010`	Challenge Required: Triggers a native 3DS challenge UI.
`5200 0000 0000 2052`	Frictionless Success: Authenticated without user interaction.
`5200 0000 0000 1039`	Unavailable: Simulates a scenario where 3DS is not available for the card.
`5100 0000 0000 0065`	Suspected Fraud: Frictionless failure due to suspected fraud.

American Express

Card Number	Expected 3DS Outcome
`3415 0209 8634 895`	Frictionless Success: Authenticated without user interaction.
`3486 3826 7931 507`	Challenge Required: Triggers a native 3DS challenge UI.
`3456 9539 9207 589`	Authentication Failed: Frictionless failure.

Challenge screen inputs

When a challenge is triggered, use the following values to simulate different transaction results within the native UI.

OTP (One-Time Password)

When the challenge screen asks for a code, enter one of the following:

OTP Code	Resulting Transaction Status	Description
`1234`	Y	Success / Authenticated.
`1111`	N	Not Authenticated.
`2222`	R	Rejected.
`3333`	U	Unavailable / Unable to complete.

Selection options

Some challenges may present a list of options (for example, “Select your favorite city”). Single-select

Paris or Nice: Returns Success (Y).

Multi-select

Paris & Lyon: Returns Success (Y).
Toulouse & Lyon: Returns Success (Y).

Best practices for testing

Verify UI transitions: Ensure your app correctly transitions from the card entry screen to the native 3DS challenge modal and back.
Test error states: Use the “Rejected” or “Failed” cards to ensure your app displays helpful messaging to the user when a card cannot be verified.
Check Backend Session: After a successful test, verify that the checkout_session_id on your server reflects the successful authentication before attempting the final transaction.

Get started

Integration guides

Best Practices

Resources

Features

Other

Adding 3DS authentication

Prerequisites

How it works

Limitations & Considerations

Implementation

1. Create a Checkout Session

2. Update SDK logic

3. Backend Authorization

Handling failed authentication

Theming

Testing and validation

Testing scenarios

Visa

Mastercard

American Express

Challenge screen inputs

OTP (One-Time Password)

Selection options

Best practices for testing

​Prerequisites

​How it works

​Limitations & Considerations

​Implementation

​1. Create a Checkout Session

​2. Update SDK logic

​3. Backend Authorization

​Handling failed authentication

​Theming

​Testing and validation

​Testing scenarios

​Visa

​Mastercard

​American Express

​Challenge screen inputs

​OTP (One-Time Password)

​Selection options

​Best practices for testing

Prerequisites

How it works

Limitations & Considerations

Implementation

1. Create a Checkout Session

2. Update SDK logic

3. Backend Authorization

Handling failed authentication

Theming

Testing and validation

Testing scenarios

Visa

Mastercard

American Express

Challenge screen inputs

OTP (One-Time Password)

Selection options

Best practices for testing