❗️

"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": {
                    "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 2.3] Get a response on the Intent creation request

• The issuing bank decides 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 the direct response on the Intent Creation Request (Step 1.3).
  Example:

{
    "intentId": "24976676782386380",
    "payments": [
        {
            "id": "249766768297820165",
            "submittedAmount": {
                "value": 501.00,
                "currency": "KZT"
            },
            "authAmount": {
                "value": 501.00,
                "currency": "KZT"
            },
            "paymentInstrument": {
                "id": "242238073190432722",
                "storedDetails": {
                    "maskedNumber": "539622******1414",
                    "holderName": "Maxim Hope",
                    "expiryMonth": 3,
                    "expiryYear": 2026
                }
            },
            "status": "AUTHORIZATION_REQUESTED",
            "additionalData": {
                "paymentId": 249766768297820160,
                "status": "AUTHORIZATION_REQUESTED",
                "details": {
                    "cReq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJkYzUzNzEyYi1hN2YwLTQzMzgtOTU1Yy0yZjk1Y2ZjODA0ZjciLCJhY3NUcmFuc0lEIjoiNDY5ZjFhMjctYzExZC00YzZmLWJiMDYtZTg2NzYyN2IyMTVlIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0",
                    "acsUrl": "https://acs.bpcprocessing.net/acs/api/3ds2/creqbrw/dc53712b-a7f0-4338-955c-2f95cfc804f7",
                }
            }
        }
    ],
    "disbursements": [],
    "clientReferenceIntentId": "1234",
    "paymentCreationErrors": [],
    "disbursementCreationErrors": [],
    "intentStatus": "IN_PROGRESS"
}

[Step CF 2.5-2.7] 
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).
• You must to catch the response from the ACS that would contain the cRes parameter to the notificationUrl used during the intent creation. cRes parameter is the key parameter that must be forwarded to us to complete the 3DS check.

[Step CF: 2.12] Forward the cRes to 8B

• When you receive 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

This step is optional, we can do auto-capture if required

[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.

PAYMENTS TESTING

Bank Card UZ has many cases to test. The detailed description is available on the dedicated page

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