❗️

"paymentMethodName": "BankCardRU"

Steps to work with Payment

[Step 1] Create a new Intent with a Payment

📘

The main method description is available in the API Reference section

• The Create Intent request is universal across all payment methods.
• Some properties are common, while others are payment-method specific.
• Method-specific properties are documented in the relevant payment-method sections, for example paymentMethod.incomingDetails and threeDSContext.

Depending on the contexts and the device the payment is being conducted on the request must contain the correctly filled objects:

• incomingDetails
• threeDSContext

Object incomingDetails description:

Object threeDSContext description for Device Channel = BROWSER:

Object threeDSContext description for Device Channel = APP:

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/"
        }
    ]
}

{
  "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": {
	   					"sdkAppID": "2f5d7a2b-9f1c-4a1e-9b8e-7d8a6b1a2c33",
					    "sdkEncData": "eyJkZXZpY2VJbmZvIjoiLi4uIn0=",
					    "sdkEphemPubKey": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2Ii4uLn0=",
              "sdkMaxTimeout": "05",
      				"sdkReferenceNumber": "3DS_LOA_SDK_PPFU_020200_00142",
      				"sdkTransID": "b6f2eb46-6b2d-4b5b-8a3f-9d2a1f4c7e11",
      				"sdkInterface": "03",
     					 "sdkUiType": "01,02,03,04,05",
  					},
            "webhookUrl": "https://google.requestcatcher.com/"
        }
    ]
}

Fields Description

[Step 2] Authorize the amount via the 3DS Authentication if required by a card-issuer

📘

This endpoint authorises bank card payments. It supports three authentication modes: no 3-D Secure, 3-D Secure 1, and 3-D Secure 2. Each mode has its own request requirements and flow, documented in separate sections.

Action Sequence

No 3DS Case

Description

When a card payment does not require a challenge (frictionless) or a 3-D Secure challenge is completed, our system sends a callback to the URL you supplied when creating the payment. The callback communicates the final authorisation status of the transaction.

🔗

Payment callback with the lates transaction status is described in the separate section

Possible statuses

3DS v1 Case

Description

When 3-D Secure v1 is required, the platform sends a callback to your webhook with the data you need to start the issuer challenge in the customer’s browser. You must render an auto-post HTML form that submits these fields to the ACS. After the challenge, the ACS returns to your termUrl; you then finalise the payment.

You will receive a callback from us with the following fields:

{
  "paReq": "eNqVUtty2kAQQO9+Q0m3QbIuW2c1Qbqg5n3mQmRkZGFuY2UtbW9jay1wYXJlcS1wYXlsb2FkLgo=",
  "acsUrl": "https://acs.visa.com/pareq",
  "termUrl": "https://your-domain.com/3ds/v1/term",
  "md": "6c2e6f9a-0f1c-4f8b-9c44-7a0b2f21c3f1",
  "errorDescription": null,
  "paymentStatus": "AUTHORIZATION_REQUESTED"
}

What you receive

From our challenge-required callback you’ll get:

• acsUrl – issuer ACS entrypoint.
• paReq – Base64 payload for this transaction.
• md – opaque value to be echoed unchanged.
• termUrl – already set to our domain. Do not modify

What you do

1. Start the challenge in the customer’s browser
   1. Initiate the challenge to acsUrl with these exact field names: PaReq, TermUrl, MD.
   2. Use the termUrl value exactly as provided. Do not replace it with your own URL.
   3. Present the issuer page in a top-level context, keep the customer informed, and provide a graceful fallback if scripts are blocked.
2. Do not capture ACS results yourself
   1. You will not receive PaRes or ACS posts.
   2. The ACS will post back to our TermUrl.

What happens next

1. In the shopper’s browser, initiate a redirect/auto-post to acsUrl, sending PaReq, MD, and TermUrl with the exact field names.
2. Display the bank’s page and wait for the shopper to complete authentication.
3. Do not receive anything on your server - the ACS will return to our termUrl.
4. Wait for our final callback with one of the statuses: AUTHORIZED, DECLINED, or ERROR.

3DS v2 Case

Description

When 3-D Secure v2 applies, the platform evaluates the transaction using your threeDSContext and either completes frictionlessly or requests a challenge. If a challenge is needed, we send a callback with the parameters (e.g., acsUrl, cReq, threeDSSessionData) to initiate the issuer challenge in the customer’s browser or mobile app (via the 3DS SDK). Once the challenge is finished, we finalise the authorisation and send your webhook the final payment status.

You will receive a callback from us with the following fields:

{
  "threeDsMethodUrl": "https://acs.issuerbank.com/3ds-method",
  "threeDsMethodData": "base64-encoded-string",
  "threeDSServerTransID": "uuid",
  "errorDescription": null,
  "paymentStatus": "AUTHORIZATION_REQUESTED"
}

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

• You or your client - the store 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

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.

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": {}
}

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:

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"
}

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.

Forward the cRes to 8B

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

[Step 3] Capture or Cancel the authorized amount

PAYMENT CAPTURE

🕑

IMPROTANT

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

• 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 30 days

• 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