Overview

The BankCardKZ payment method uses 3DS version 2 (3DSv2) for cardholder authentication.

To help you test different authentication and authorisation flows in the sandbox, we’ve introduced the concept of a “written destiny” for each transaction.

A written destiny lets you define exactly how a transaction will behave at each stage of the 3DSv2 flow - from intent creation to capture - without changing any other parameters.

This approach simplifies automated testing and enables deterministic emulation of success, failure, and edge-case scenarios.

Reference Diagram

The entire process is illustrated in the flow diagram below.

As you can see, there are several possible paths a transaction can follow - depending on iframe requirements, challenge outcomes, authorisation results, and post-authorisation actions.

Download the image in high resolution

Defining the Transaction Destiny

The destiny is set via the description field in the Intent creation request body.

⚠️

Important:

There are two description fields in the API structure - one in the intent, and another in payments[].description. Use only the intent-level field. The one inside payments[] will be ignored for testing purposes.

• Each destiny consists of a chain of keywords corresponding to specific flow outcomes.
• These keywords are grouped by flow sections, and only one keyword can be chosen per section.
• Join your selected keywords with the | (pipe) symbol to form a single string.
• If the platform detects that the actual transaction behaviour does not match the destiny you provided, it will return an ERROR and stop processing.

Example

For example, to simulate this sequence:

You should define the destiny as follows: "description": "NoIFrame|Challenge-Success|AuthSuccess|InnitCapture|Capture-Success"

{
    "clientReferenceId": "1234",
    "description": "Iframe-Success|Challenge-Success|AuthSuccess|InitCapture|Capture-Success",
    "payments": [
        {
            "paymentInstrument": {
                "paymentMethodName": "BankCardKZ",
                "incomingDetails": {
                    "brand": "VISA",
                    "number": "4111111111111111",
                    "cvv": "123",
                    "holderName": "Will Rush",
                    "expiryMonth": "12",
                    "expiryYear": "2035"
                }
            },
            "submittedAmount": {
                "value": 1000,
                "currency": "KZT"
            },
            "authCurrencyCode": "KZT"
        }
    ]
}

List of Supported Cases

Download the image in high resolution

List of Cases in text