Authentication by payment system
Overview
Authentication by payment system is used for ensuring security of online purchases made with cards of certain payment systems and is mandatory when such purchases are processed.
This type of authentication replaces 3‑D Secure and is performed in a similar fashion with the use of one-time verification codes (One Time PIN, OTP) that the customer receives in messages. However, unlike the case of 3‑D Secure when the customer enters verification codes on the side of the issuer, the customer enters verification codes in merchant's web service.
To support the customer authentication by payment system, make sure you configured the web service to accept verification codes from the customer and to submit them to the payment platform.
Workflow
From a technical standpoint, the authentication by payment system employs the procedure of submitting additional payment information. After the payment platform completes the initial request processing, it sends to the web service a callback with request to provide a verification code. In its turn, your web service is required to receive the verification code from the customer and to send it in the request for continuing the payment processing to the platform.
The wait time for the request to arrive depends on the payment method and is defined as the time between the moment the need to submit additional information is detected and the moment the request from the web service is received. If no request is received by the platform before the timeout expires, the payment will be automatically rejected. As soon as the payment platform receives all the requested data, the payment process resumes.
Thus, in the process of interaction with the payment platform, your web service is required to do the following:
- Accept the callback with request to provide a verification code.
- Accept the verification code from the customer.
- Send the request with the verification code to the payment platform.
In some regions, the payment platform allows you to request resending message with a verification code to the user. For more information about this functionality, see Resending the verification code. For more information about availability of this functionality in your region, contact your account manager.
For more information about responding to callbacks with request for additional information, see Submission of additional payment information. Examples of callback and request data used in customer authentication by payment system are covered in the following section.
Data format
Formats of callbacks and requests exchanged during the procedure of authentication by payment system are identical to those used in the procedure of submitting additional payment information except for several parameters discussed further in this section.
The callback body with the request for the verification code contains the following additional parameters:
- provider_extra_fields—object with the details of verification code submission
- new_attempt_time—deadline for verification code submission in the Unix timestamp format.
To ensure timely payment confirmation, you need to send a request with a confirmation code before the deadline specified in the new_attempt_time parameter expires. The request with the verification code is send by using the procedure of submitting additional payment information. Once the payment platform receives the verification code, the payment processing by the platform and provider service continues and the web service receives the final callback.
{
"provider_extra_fields": {
"new_attempt_time": 1681736775
},
"clarification_fields": [
"confirm_code"
],
"customer": {
"id": "123456"
},
"account": {
"number": "123456******1234",
"type": "uzcard",
"card_holder": "John Dow",
"expiry_month": "05",
"expiry_year": "2025"
},
"project_id": 100992,
"payment": {
"id": "payment_12",
"type": "purchase",
"status": "awaiting clarification",
"date": "2023-04-19T12:12:40+0000",
"method": "card",
"sum": {
"amount": 204000,
"currency": "UZS"
},
"description": ""
},
"operation": {
"sum_initial": {
"amount": 204000,
"currency": "UZS"
},
"sum_converted": {
"amount": 204000,
"currency": "UZS"
},
"code": "19999",
"message": "Awaiting processing",
"provider": {
"id": 11131,
"payment_id": "",
"auth_code": "",
"endpoint_id": 11131
},
"id": 42737010081577,
"type": "sale",
"status": "awaiting clarification",
"date": "2023-04-19T12:12:40+0000",
"created_date": "2023-04-19T12:12:38+0000",
"request_id": "d8ce5b71...0-00042738"
},
"signature": "bBw5bW5hVs...oQUXQfxnuhP5RvN/+YEEZe1t6gS10Uw=="
}
{
"general": {
"project_id": 11,
"payment_id": "pID-14",
"signature": "v7KNMpfog...=="
},
"additional_data": {
"confirm_code":"123456"
}
}
Resending the verification code
There may be situations in which the user does not receive the message with the verification code. To address this issue, in some regions, the payment platform provides the functionality to request resending the verification code to the user. For more information about the availability of this functionality, check with your supervising manager. The remainder of this section describes how to use and format a resend request, and provides examples of callback and request to resend verification code.
If the callback with the request for the verification code contains the resend object, then the verification code resend functionality is available in the current payment. The resend object contains the following parameters:
- new_attempt_time—deadline for verification code submission to the payment platform in the Unix timestamp format. You can request the platform to resend the verification code only after after this deadline expires.
- available_attempts_number—the number of remaining attempts to resend the verification code. This parameter determines how many times you can submit the request to resend the verification code to the payment platform.
The following is the callback with the resend object which tells you that there is one attempt left to request the payment platform to resend the verification code.
{
"provider_extra_fields": {
"available_customer_actions": {
"resend": {
"new_attempt_time": 1681736775,
"available_attempts_number": 1
}
}
},
"clarification_fields": [
"confirm_code"
],
"customer": {
"id": "1"
},
"account": {
"number": "12345678******1234",
"type": "humo",
"card_holder": "JACK ONEAL",
"expiry_month": "08",
"expiry_year": "2027"
},
"project_id": 29781,
"payment": {
"id": "PAYMENT_123456",
"type": "purchase",
"status": "awaiting clarification",
"date": "2023-04-17T13:05:14+0000",
"method": "card",
"sum": {
"amount": 1000,
"currency": "UZS"
},
"description": "PAYMENT_1234"
},
"operation": {
"sum_initial": {
"amount": 0,
"currency": ""
},
"sum_converted": {
"amount": 0,
"currency": ""
},
"code": "0",
"message": "Success",
"provider": {
"id": 12345,
"payment_id": "",
"auth_code": "",
"endpoint_id": 12345
},
"id": 123456789,
"type": "customer action",
"status": "success",
"date": "2023-04-17T13:05:15+0000",
"created_date": "2023-04-17T13:05:14+0000",
"request_id": "05027333"
},
"signature": "MiMeZogWjdhqoO3rPGFmDxf...w0UHQ=="
}
Normally, your web service receives a verification code from the user and sends it to the payment platform before the deadline specified in the new_attempt_time parameter. But further on we will only describe the scenario in which the user does not enter the verification code within the deadline and the web service decides to request the platform to resend the verification code.
The scenario described below assumes that the available_attempts_number parameter in the last callback with the request for additional information is greater than zero, or, in other words, there is at least one attempt available to request for resending the verification code.
- The web service waits for the user to enter a verification code within the deadline specified in the new_attempt_time parameter.
It is strongly recommended to prevent the user from requesting the verification code resend before the deadline for entering the verification code expires (for example, by disabling the corresponding button).
- The web service does not receive the verification code from the user.
It is strongly recommended to prevent the user from entering the verification code after the deadline for entering the verification code expires (for example, by disabling the corresponding input box) and, alternatively, to enable the user to ask for resending the verification code (for example, by enabling the corresponding button).
- If the user requests the web service to resend the verification code, the web service sends the request to resend the verification code to the
/v2/customer/action/resendendpoint.The request format is described further in this section.
CAUTION: Your web service is allowed to request the payment platform to resend the verification code only after the deadline for the verification code submission expires. - The platform responds with a new message to the user with the verification code and, also, sends another callback to the web service with the request to provide the verification code.
In this callback, the resend object contains the new verification code submission deadline in the new_attempt_time parameter and the number of the remaining attempts to request resending of the verification code in the available_attempts_number parameter.
- There are options available on this step:
- The user enters the verification code in your web service and the web service sends the code to the /v2/payment/clarification endpoint by using the procedure of submitting additional payment information.
Once the web service submits the request with the verification code to the payment platform, no further verification code resend is possible.
- The user fails to enter the verification code in your web service within the deadline
In this case, the web service can one more time request the verification code by following steps 2-4, but only if the available_attempts_number parameter is greater than zero in the last callback with the request for the verification code.
- The user enters the verification code in your web service and the web service sends the code to the /v2/payment/clarification endpoint by using the procedure of submitting additional payment information.
This verification code resend procedure is available only in selected regions. For more information about availability of this functionality in your region, contact your account manager.
Format of the request for resending the verification code
Your web service sends the request for resending the verification code to the /v2/customer/action/resend endpoint which belongs to the /v2/customer/action/{action_name} group by using POST (HTTP) method. The request must contain the following objects and parameters:
- general—object that contains general request identification information:
- project_id—ID of the project to which the payment is related
- payment_id—payment ID unique within the project
- signature—signature generated after all of the required parameters are specified (for more information, see Signature generation and verification)
- customer—object that contains customer information:
- ip_address—customer device IP
Below, you will find the sample request for resending the verification code.
{
"general": {
"project_id": 1234,
"payment_id": "payment_47",
"signature": "PJkV8ej...9MTO8yJA=="
},
"customer": {
"ip_address": "198.51.100.47"
}
}