Payments with 3D Secure are implemented in three stages: initiation, verification, and completion. In the initiation request to the Odero API, a callback URL is provided, through which the 3D Secure status can be communicated. Using this URL, the business participant in their workflow specifies the payment ID and sends a request to complete the payment, ensuring the entire process is carried out from start to finish.
Details about the endpoint and HTTP method used to initiate a 3D Secure payment are provided below:
| HTTP Metod | URL |
|---|---|
POST |
/payment/v1/card-payments |
Unlike other payments, when implementing payments using 3D Secure, sending the callbackUrl parameter is mandatory. In this context, the mandatory parameters for initiating a 3D Secure payment are as follows:
| Parameter Name | Type | Mandatory | Description |
|---|---|---|---|
conversationId |
string |
No | The value "boomerang," which can be sent in the request and accepted in the response. Used to link different requests. Typically, it is the order number associated with the business participant's payments. |
price |
decimal |
Yes | Total payment amount. Should be equal to the sum of products/services in the cart. |
paidPrice |
decimal |
Yes | Total amount the customer needs to pay, calculated considering commissions and discounts. In the case of partial or full payment from the wallet, the amount deducted from the wallet is also included in this sum. |
walletPrice |
decimal |
No | The amount deducted from the customer's wallet, specified in the buyerId parameter. Mandatory for partial or full wallet deductions. In the case of full deductions from the card or absence of buyerId, it can be sent as 0. (Default: 0) |
installment |
integer |
Yes | Number of monthly installments for the payment. Can be sent as 1 for a one-time payment. Possible values: 1, 2, 3, 6, 9, and 12. |
buyerId |
long |
No | Buyer ID associated with the payment. This ID belongs to Odero systems, not the ID value in the business participant's systems. |
currency |
Currency |
Yes | Refer to: Currencies The currency in which the payment is accepted. |
paymentGroup |
PaymentGroup |
Yes | Refer to: Payment Groups |
callbackUrl |
string |
Yes* | The address that will be used to deliver the result from the bank to the business participant when making a payment using 3D Secure (see 3D Secure Payment Receipt) |
card |
Card |
No | (See Card Information) Information about the card for which the deduction will be made. Not required for full deductions from the wallet (i.e., when paidPrice equals walletPrice). |
posAlias |
string |
No | Used for TOKENGATE operations. If filled, the payment will be made through this POS. Refer to: Gateway Operations |
items |
PaymentItem[] |
Yes | (See Payment Information) Information about the payment breakdown. At least one breakdown must be sent, and the sum of all sent breakdowns must be equal to the price value. |
*: In normal conditions, this field is optional, but it is marked as mandatory for payments made through the General Payment page.
The parameters returned as a result of the 3D Secure payment process adhere to the rules specified in the Refund Formats section on the main API documentation page. In the absence of a systematic or structural error, the sub-object parameters returned in the data parameter are as follows:
| Название параметра | Тип | Hər Zaman Mövcuddur | Описание |
|---|---|---|---|
htmlContent |
string |
Да | Structure of the HTML code of the 3D Secure form, which will be presented to the user. This value is sent in Base64 encoding and should be decoded by the business participant before displaying |
The process of 3D Secure payment, starting with the initiation request sent by the business partner, continues with user verification. For this, the HTML structure contained in the response to the initiation request must be decoded and displayed to the user.
After the user enters the confirmation code they received, the verification result is transmitted to the Odero API by the respective bank. Odero API sends a request to the callback URL provided by the business partner during the payment initiation request, saving the received result along with some payment information.
The following parameters are transmitted as form variables using the HTTP POST method. The parameters contained in the request that Odero will send to the callbackUrl after confirmation will be as follows:
| Parameter Name | Type | Always Present | Description |
|---|---|---|---|
status |
string |
Yes | Value expressing the status of the 3D Secure check. If the check is successful, the value SUCCESS will be received; otherwise, FAILURE |
conversationId |
string |
No | Value of the conversationId parameter sent in the payment initiation request |
paymentId |
long |
No | Sent in case of successful verification. This is the identifier created by the Odero API associated with the payment |
After Odero sends the result to the business partner through the callbackUrl request for successful payments, the business partner must complete the process by sending a completion request to the Odero API. This request must be sent within the timeout period. If the completion request is not sent or is not confirmed after a successful callbackUrl invocation, the transaction will not be completed. If this does not happen, or if it is impossible to access the callbackUrl after confirmation, the transaction will remain in pending status and will be displayed in yellow on the business partner's panel.
Information about the endpoint and HTTP method used to complete the 3D Secure payment is provided below:
| HTTP Metod | URL |
|---|---|
POST |
/payment/v1/card-payments/3ds-complete |
Completion request parameters for payments that have passed the verification stage are as follows:
| Parameter Name | Type | Always Available | Description |
|---|---|---|---|
paymentId |
long |
Yes | The ID of the payment created by the Odero API and passed to the callbackUrl in connection with the payment. |
The response to the completion request for payments made using 3D Secure is similar to a standard payment and contains details related to the payment. For the response format and the parameters it contains, refer to: Payment Reception Parameters - Return