❗️

"paymentMethodName": "BankCardKZ"

Payment Method Features

Payments

Workflow: Payment (with 3DS) & Refund

🔗

More about 3DS available on the 3DS v2: Workflow Description page

High-resolution image is available on the link: 3DS v2. - KZ Bank Cards

PAYMENT AUTHORIZATION STEPS

[Step 1.3] You need to create a new intent

• Use the following API method to create an intent: POST /processing/api/v1/intents.
• When creating the intent, complete the Payment object.
• Most fields are common across all payment methods and are thoroughly described in the API Reference section.
• However, some fields are method-specific (for example, payments[].paymentInstrument.incomingDetails).
• Ensure these fields are completed accurately so that we can process your request correctly.

Request Example

{
  "clientReferenceId": "12355884566454255875454157",
    "payments": [
        {
            "payer": {
                "firstname": "Megan",
                "lastname": "Fox",
                "phone": "+6228128011",
                "email": "[email protected]",
                "countryIsoCode": "KZ",
                "locale": "de-DE",
                "taxIdentification": "7852",
                "merchantPayerReference": "12357"
            },
            "paymentInstrument": {
                "paymentMethodName": "BankCardKZ",
                "incomingDetails": {
                    "brand": "VISA",
                    "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/"
        }
    ]
}

payments[].paymentInstrument.incomingDetails for Payment Method "BankCardKZ"

payments[].threeDSContext for Payment Method "BankCardKZ"

[Step 1.7] Get a response on the Intent creation request

• After accepting the Intent creation request, we validate the incoming details. For each individual Payment, we create a separate transaction and begin processing them simultaneously.
• For transactions involving bank cards, additional information may be required for 3D Secure verification.
• This payment method uses the 3DS v2 protocol, which may require one additional step to collect metadata about the payer before the actual verification.
• This step if Optional. If the processing bank decides to perform this pre-authorisation check, the response body will include a dedicated object containing all the necessary information to complete the check.
• The object payments[].additionalData will include the following fields:
  • threeDsMethodUrl
  • threeDsMethodData
  • threeDsVersion
  • threeDSServerTransID
• These fields will be required in the later steps of the 3DS workflow.

payments[].additionalData

"additionalData": {
    "threeDsMethodUrl": "https://acs.issuerbank.com/3ds-method",
    "threeDsMethodData": "base64-encoded-string",
    "threeDsVersion": "2.1.0",
    "threeDSServerTransID": "uuid"
    }

[Step 1.10] Send a POST request to MethodUrl with the "threeDsMethodData": "base64-encoded-string" via the Hidden iFrame

• You or your client - the sore that initiated the payment must send the threeDSMethodData payload be POSTed from the cardholder’s browser to the ACS Rendering URL via the hidden iframe.
• Hidden iframe allows this POST to occur silently without redirecting or disturbing the shopper’s checkout page.
• The ACS may return JavaScript or tracking pixels to collect device data. Performing this in an iframe preserves the user experience while meeting security requirements.

Implementation Steps for Your Storefront

1. Receive the threeDsMethodUrl and threeDsMethodData.
2. Dynamically create a hidden iframe element in your checkout page.
3. Inject an HTML form into the iframe that:
   1. Uses the POST method.
   2. Has the action attribute set to threeDsMethodUrl.
   3. Contains a single hidden input named threeDSMethodData with the value from our response.
4. Auto-submit the form inside the iframe.
5. Record the fact that the hidden iframe was onloaded (will be used later
   1. methodCompInd = Y - for success
   2. methodCompInd = N - for failure
6. Return the result of iframe loading "methodCompInd" to us (step 1.13)

Integration Notes

• Do not decode or modify threeDsMethodData; forward it exactly as received.
• Do not use server-to-server calls (e.g., cURL) for this step—these will not satisfy ACS device fingerprinting requirements.
• Adapt for your framework:
  • For React, Vue, Angular, etc., inject the iframe and form in a lifecycle hook or DOM utility.
  • If you enforce Content Security Policy (CSP), allow posting to the ACS domain (threeDsMethodUrl) and place inline JS in an approved script file or use a nonce.
• Handle timeouts gracefully: Continue the authentication flow even if no ACS callback arrives within ~10 seconds.
• Keep the iframe mounted until you either receive the ACS notification or hit your timeout.

[Step 1.13] Return the result of the iframe loading and the gathered metadata

• On the previous step the Storefront must have conducted the hidden iframe loading
• The gathered information must be sent to us via the dedicated API Method

{
  "protocol": "2.1.0",
  "methodCompInd": "Y",
  "serverTranId": "abc-123",
  "additionalData": {}
}

[Step 2.1] Get the webhook with the transaction status OR the 3DS details

• At the-pre auth state we provided the metadata describing the payer's profile.
• The Bank issuer base on this information making a decision if they want to confirm the payers identity or not. based on this decision two different flows might be launched:
  • Frictionless flow - give some desciriipion here
  • Challenge flow - give some description here
• If the Frictionless flow was accommodated, then the transaction will be authorised or declined immediately
• If the Challenge flow was accommodated, then the bank issuer provide us the details for 3ds auth. The we. redirected to you
• You can get this information via the webhook. Here are the examples:

[Step FF/CF 2.3] Receive the webhook with the transaction status or 3DS details

• During the pre-authorisation stage, we provided metadata describing the payer’s profile.
• The issuing bank uses this information to decide whether to verify the payer’s identity. Based on this decision, one of two flows is initiated:
  • Frictionless flow - The issuer considers the risk low and processes the transaction without further user interaction.
  • Challenge flow - The issuer requires additional verification, such as a one-time password or biometric confirmation, to authenticate the payer.
• If the Frictionless flow is used, the transaction will be authorised or declined immediately.
• If the Challenge flow is required, the issuer will send us the details necessary to continue the 3DS authentication, and we will pass this information to you.
• You will receive this information through a webhook. Examples are provided below:

    {  
      "status": "AUTHORIZED",
      "errorCode": "CODE_PT0000",
      "errorMessage": "string"
    }

{
"cReq": "eyJ0cmFuc1R5cGUiOiJD...",
"acsUrl": "https://acs.visa.com/pareq",
"errorDescription": null,
"threeDSSessionData": "session-xyz-987654321",
"paymentStatus": "AUTHORIZATION_REQUESTED"
}

[Step CF 2.5] 
Load the issuer’s challenge UI for the cardholder

• During this step the Storefront must render an iframe and auto-POST the following fields to the acsURL provided in the webhook or response:
  • cReq – the challenge request payload generated for this transaction.
  • threeDSSessionData – session metadata that links the challenge to your transaction.
• The iframe will load the issuer’s challenge user interface, where the cardholder completes the authentication step (e.g. entering a one-time password, using biometric verification, or confirming via their banking app).
• The store front must to catch the response from the ACS that would contain the cRes parameter. cRes parameter is the key parameter that must be forwarded to us to complete the 3DS check.

[Step CF: 2.10] Forward the cRes to Us

• When your Storefront receives the cRes (Challenge Response) from the Access Control Server (ACS), you must forward it to us to finalise the 3DS authentication.
• Use the following endpoint to submit this data: Complete 3DS authentication for a payment
• Once received, we will complete the 3DS verification and send you a webhook with the final transaction status - either AUTHORIZED or DECLINED.
• If the transaction is successfully AUTHORIZED, you may proceed to either capture or cancel the transaction according to your business flow.

PAYMENT CAPTURE

🕑

IMPROTANT

The timeframe between the authorization and capturing must not exceed 7 days

[Step 3.1] Send a Capture Request

• To finalise the payment transaction and deduct funds from the payer’s account, you must send a separate Capture request.
• Use the following endpoint: Update Payment status and specify the action you wish to perform:
  • status = CAPTURED - to capture the authorised amount.
  • status = CANCELLED - to cancel the authorisation and release the reserved funds
• After receiving your request, we will initiate the capture process and send you a standard webhook with the updated transaction status.

PAYMENT CANCELLATION

🕑

IMPROTANT

The timeframe between the authorization and cancellation must not exceed 7 days

[Step 4.1] Send a Cancellation Request

• To cancel the payment transaction and release funds on the payer’s account, you must send a separate Cancellation request.
• Use the following endpoint: Update Payment status and specify the action you wish to perform:
  • status = CAPTURED - to capture the authorised amount.
  • status = CANCELLED - to cancel the authorisation and release the reserved funds
• After receiving your request, we will initiate the capture process and send you a standard webhook with the updated transaction status.

REFUNDS

📘

• Refunds can be made only from the day after the customer’s card was charged (after confirmation).
• They are allowed only for transactions made within the last 180 days
• They cannot exceed the total value of confirmed transactions for the current day.

[Step 5.1] Send a Refund Request

• To initiate the refund (full or partial) to the payer's original payment instrument, you must send a separate Refund request.
• Use the following endpoint: Create Refund inside existing Intent and specify the following parameters:

• After the creation of the refund request you must wait for the callback, that will provide you with the latest transaction status