❗️
This integration method is DEPRECATED and should not be used for new integrations
Please follow the new simplified flow described on the page where we simplified the 3DS processing and less steps involved

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:

Step	Keyword
3DS challenge	Challenge-Success
Authorisation is successful	AuthSuccess
A capture request is sent	InitCapture
The payment transaction is captured successfully	Capture-Success

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

{
  "clientReferenceId": "12355884566454255875454157",
  "description": "Iframe-Success|Challenge-Success|AuthSuccess|InitCapture|Capture-Success",

    "payments": [
        {
            "payer": {
                "firstname": "Megan",
                "lastname": "Fox",
                "phone": "+6228128011",
                "email": "[email protected]",
                "countryIsoCode": "KZ",
                "locale": "de-DE",
                "taxIdentification": "7852",
                "merchantPayerReference": "12357"
            },
            "paymentInstrument": {
                "paymentMethodName": "BankCardKZ",
                "incomingDetails": {
                    "number": "4111111111111111",
                    "cvv": "123",
                    "holderName": "Will Rush",
                    "expiryMonth": "12",
                    "expiryYear": "2035"
                }
            },
            "submittedAmount": {
                "value": 200.1,
                "currency": "KZT"
            },
            "authCurrencyCode": "KZT",
            "threeDSContext": {
                "merchantLocalDateTime": "01.02.2012 18:34:58",
                "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
                "browserIp": "147.30.44.72",
                "browserLanguage": "ru",
                "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
                "browserJavaEnabled": false,
                "browserColorDepth": "24",
                "browserScreenHeight": "864",
                "browserScreenWidth": "1536",
                "browserTZ": "-360",
                "browserJsEnabled": false,
                "notificationUrl": "https://secure.examplepay.com/3ds/complete",
                "requestorUrl": "https://www.merchantshop.com"
            },
            "webhookUrl": "https://google.requestcatcher.com/"
        }
    ]
}

List of Supported Cases

Download the image in high resolution

List of Cases in text

Case	Description
CASE1	Frictionless\|AuthSuccess\|InitCapture\|Capture-Success
CASE2	Frictionless\|AuthSuccess\|InitCapture\|Capture-Error
CASE3	Frictionless\|AuthSuccess\|InitCancellation\|Cancellation-Success
CASE4	Frictionless\|AuthSuccess\|InitCancellation\|Cancellation-Error
CASE5	Frictionless\|AuthDecline
CASE6	Challenge\|AuthSuccess\|InitCapture\|Capture-Success
CASE7	Challenge\|AuthSuccess\|InitCapture\|Capture-Error
CASE8	Challenge\|AuthSuccess\|InitCancellation\|Cancellation-Success
CASE9	Challenge\|AuthSuccess\|InitCancellation\|Cancellation-Error
CASE10	Challenge\|AuthDecline
CASE11	Challenge\|AuthExpired