At iyzico, following the recent HMACSHA256 update, we launched the payment/v2/3dsecure/auth endpoint alongside the existing payment/3dsecure/auth endpoint. This endpoint is used to finalize registered 3D payments and retrieve details of the corresponding transactions by including the final amount charged to the customer’s card, its conversationId and paymentId.
With this, more reliable validation techniques can be used to complete the respective payment. As mentioned on the Response Signature Validation, the variables listed in the request table, returned as a result of the payment request, play a crucial role in this process.
As shown on the Response Signature Validation, when a signature is generated for the encrypted payload on both sides and these signatures are equal, the respective payment is successfully completed.
The parameters that need to be sent to the service are as follows:
Create 3DS v2 Payment
post
After the verification step, both the v1 and the new-generation v2 endpoints can be used to finalize the payment. However, to align with more advanced and secure technologies, the use of the v2 endpoint is recommended.
Header parameters
AuthorizationstringRequired
Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.
Example: IYZWSv2 aXBzaWduYXR1cmU...
Content-TypestringRequired
Content-Type value.
Example: application/json
Body
localestring · enumOptional
Language code. Default; tr
Example: enPossible values:
paymentIdstringRequired
Payment ID returned after 3DS initialization.
Example: 25146302
conversationIdstringOptional
Unique ID for request/response correlation.
Example: conversationId
paidPricedecimalRequired
Collected amount to be used in 3DS v2 completion. Must match the paidPrice sent in INIT 3DS.
Example: 1
basketIdstringRequired
Basket ID (must match INIT 3DS basketId).
Example: basketId
currencystring · enumRequired
Currency. Default; TRY (must match the value sent in INIT 3DS).
The payment/3dsecure/auth endpoint employs the standard 3D Secure 1.0 protocol, offering basic authentication with a simpler structure, making it easier for legacy systems to integrate. In contrast, the payment/v2/3dsecure/auth endpoint is built on the more advanced 3D Secure 2.0 protocol, which enhances security through richer data points for risk analysis and smoother integration with modern systems. While payment/3dsecure/auth is a reliable option for basic transactions, payment/v2/3dsecure/auth offers superior security, improved user experience, and better compliance with evolving payment regulations. We recommend transitioning to payment/v2/3dsecure/auth for these benefits.
