Payment with your own 3DS Server

3DS Server is a component of 3D Secure technologies that may be implemented in the payment gateway or on your side. If you have your own 3DS Server, you can use it for 3D Secure authorization on your side, and then just indicate the fact of such authorization in API requests. To enable this feature, contact our support team.

If you use your own 3DS Server, then in every payment request - paymentOrder.do, paymentOrderBinding.do or instantPayment.do - include the following additional parameters in the jsonParams block: eci, cavv, xid, threeDSProtocolVersion, and authenticationTypeIndicator. These parameters are described below.

Parameters for own MPI/3DS Server

eci

eci parameter - Electronic commerce indicator (ECI) received from your 3-D Secure Server. It shows the security level ensured during payment. The DS server sets this parameter based on the authentication results and in accordance with the features of the merchant verification process.

ECI codes may differ depending on the payment system. The most commonly used ECI codes are given below:

cavv, xid

If ECI value differs from the ones used for SSL authorizations, it is also necessary to pass the following parameters:

• cavv - cardholder authentication value;
• xid - identifier of the 3DS authentication transaction of the cardholder on the 3DS server (ARes.dsTransID value received from ACS).

threeDSProtocolVersion

Additionally, you can pass the threeDSProtocolVersion parameter (version of 3DS protocol) in a payment request. It can take the following values:

• 1.0.2 - for 3DS 1

• 2.1.0 - for 3DS 2 (discontinued by IPS)

• 2.2.0 - for 3DS 2

If threeDSProtocolVersion is not passed in the request, then its default value is assumed to be 1.0.2 - for 3DS 1 or 2.1.0 - for 3DS 2.

authenticationTypeIndicator

authenticationTypeIndicator parameter (payment authentication type) is required for payment via your own 3DS Server with 3DS 2.

For payments with 3DS 1 or SSL, this parameter is optional and is defined automatically depending on ECI value.

Request example

curl --request POST --url 'https://api.uat.all2pay.net/v1/paymentOrder.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userName": "test_user",
    "password": "test_user_password",
    "cardholderName": "TEST CARDHOLDER",
    "cvc": "123",
    "seToken": "RJ7Pzbt...",
    "mdOrder": "2dc811e7-8d1c-407a-bd25-a4f41f96cc60",
    "jsonParams": {
        "eci": "02",
        "cavv": "AkZO5XQAA0rhBxoaufa+MAABAAA=",
        "xid": "5010857f-8d3f-74e1-9c5a-54a000cc4110",
        "threeDSProtocolVersion": "2.2.0",
        "authenticationTypeIndicator": "5"
    }
}'

If you use your own 3DS Server, the corresponding payment response does not contain 3D Secure-related parameters, such as redirect, termUrl, acsUrl, and paReq.

Response example

{
    "errorCode": 0,
    "info": "Your payment is proceeded, redirecting...",
    "is3DSVer2": false,
    "mdOrder": "d0b8ad07-0601-4afb-b5dc-605d4b9db863",
    "redirect": "https://mybestmerchanturl.com/success?orderId=d0b8ad07-0601-4afb-b5dc-605d4b9db863&lang=ru",
    "transactionState": "DEPOSITED"
}

Routing with your own MPI/3DS Server

When Partner uses their own MPI/3DS Server, it is not allowed to balance payments between multiple banks in a percentage ratio. This restriction is due to the fact that this routing method does not allow you to predict which bank the order will be routed to.

To correctly pass 3D Secure in a way that ensures authentication data does not conflict with authorization data, the Partner must know in advance which bank the order will be routed to. The authentication request (AReq / PAReq) contains the merchant ID (acquirerMerchantID), which is unique for each Partner in every bank. If the same ID is used throughout the requests, international payment systems may detect a discrepancy and deny authorization.

When using routing rules without balancing, the Partner can determine which bank the order will be routed to based on the routing rules returned in the /settings/getRouterParams.do request. This allows using the correct acquirerMerchantID when passing 3DS.