3DS Scenarios

The 3DS Scenarios API allows a merchant to manage custom 3D Secure authentication scenarios for the hosted 3DS flow. Scenarios define specific authentication behaviors and response patterns for testing purposes.

Overview

3DS Scenarios are configuration templates that define how 3D Secure authentication should behave for transactions. Use scenarios to:

Test specific authentication flows and outcomes
Configure consistent challenge behaviors across payment tests
Simulate different 3DS authentication scenarios

3DS Scenarios are only available for the hosted 3DS flow. For other integration methods, refer to the 3DS testing guide to use test cards from the underlying 3DS providers.

Registering a scenario

var res = await sdk.ThreeDsScenarios.CreateAsync(threeDSecureScenarioCreate: new ThreeDSecureScenarioCreate() {
    Conditions = new ThreeDSecureScenarioConditions() {
        CardNumber = "4242424242424242",
    },
    Outcome = new ThreeDSecureScenarioOutcome() {
        Version = "2.2.0",
        Authentication = new ThreeDSecureScenarioOutcomeAuthentication() {
            TransactionStatus = "Y",
        },
    },
});

conditions := components.ThreeDSecureScenarioConditions{
    CardNumber: gr4vy.String("4242424242424242"),
}

outcome := components.ThreeDSecureScenarioOutcome{
    Version: "2.2.0",
    Authentication: &components.ThreeDSecureScenarioOutcomeAuthentication{
        TransactionStatus: "Y",
    },
}

scenarioCreate := components.ThreeDSecureScenarioCreate{
    Conditions: conditions,
    Outcome:    outcome,
}

res, err := client.ThreeDsScenarios.Create(ctx, scenarioCreate)

CreateThreeDsScenarioResponse response = gr4vyClient.threeDsScenarios().create()
    .threeDSecureScenarioCreate(ThreeDSecureScenarioCreate.builder()
        .conditions(ThreeDSecureScenarioConditions.builder()
            .cardNumber("4242424242424242")
            .build())
        .outcome(ThreeDSecureScenarioOutcome.builder()
            .version("2.2.0")
            .authentication(ThreeDSecureScenarioOutcomeAuthentication.builder()
                .transactionStatus("Y")
                .build())
            .build())
        .build())
    .call();

ThreeDSecureScenario scenario = response.threeDSecureScenario().orElse(null);

$scenarioCreate = new ThreeDSecureScenarioCreate(
    conditions: new ThreeDSecureScenarioConditions(
        cardNumber: '4242424242424242'
    ),
    outcome: new ThreeDSecureScenarioOutcome(
        version: '2.2.0',
        authentication: new ThreeDSecureScenarioOutcomeAuthentication(
            transactionStatus: 'Y'
        )
    )
);

$response = $sdk->threeDsScenarios->create($scenarioCreate);
$scenario = $response->threeDSecureScenario;

scenario = client.three_ds_scenarios.create(
    conditions={
        "card_number": "4242424242424242"
    },
    outcome={
        "version": "2.2.0",
        "authentication": {
            "transaction_status": "Y"
        }
    }
)

const scenario = await gr4vy.threeDsScenarios.create({
    conditions: {
        cardNumber: "4242424242424242"
    },
    outcome: {
        version: "2.2.0",
        authentication: {
            transactionStatus: "Y"
        }
    }
});

A 3DS scenario is used any time its conditions match a new transaction. A scenario doesn’t need to match every condition to apply. Gr4vy picks the scenario with the most matching conditions, so a scenario can apply when only one of its conditions matches, such as the card number. When two scenarios match the same number of conditions, the oldest one applies.

Use a different card number for each scenario. Scenarios that share a card number can match each other’s transactions.

Simulating a card that isn’t enrolled

To simulate a card that isn’t enrolled for 3-D Secure, set the outcome version to null. Gr4vy treats the matching transaction like a real card that isn’t enrolled. The transaction continues without 3-D Secure, unless a Flow rule forces 3-D Secure, in which case it’s declined. The authentication object is still required, but its value isn’t used.

{
  "conditions": {
    "card_number": "4111111111111111"
  },
  "outcome": {
    "version": null,
    "authentication": {
      "transaction_status": "Y"
    }
  }
}

Once created, you can manage scenarios using the 3DS Scenarios API endpoints, such as List 3DS Scenarios.

Get started

Integration guides

Best Practices

Resources

Features

Other

3DS Scenarios

Overview

Registering a scenario

Simulating a card that isn’t enrolled

​Overview

​Registering a scenario

​Simulating a card that isn’t enrolled

Overview

Registering a scenario

Simulating a card that isn’t enrolled