Response Signature Validation

This page was prepared to provide detailed guidance on implementing response signature validation using iyzico's API. Response signature validation is essential for ensuring the authenticity and integrity of data exchanged between merchants and iyzico, particularly in financial transactions. By following the instructions on generating and validating HMAC SHA256 signatures, developers can secure their applications against tampering and unauthorized access. This enhances the overall security of the transaction process, protecting both merchants and customers.

Overview

The signature parameter will be used to validate the service response by utilizing specific response parameters and the merchant's secretKey, thereby enhancing service security between merchant and iyzico using HMAC SHA256.

The signature parameter exists on following endpoints;

• Non-3DS Endpoints

• 3DS Endpoints

• "callbackUrl" Redirection

• Checkout Form(CF) & PayWithiyzico(PWI) Endpoints

• Refund Endpoints

The signature value must be created by using the parameters from the iyzico API responses.

Non-3DS Endpoints

Services	Endpoint	Parameter Order
Non-3DS	/payment/auth	paymentId, currency, basketId, conversationId, paidPrice, price
Non-3DS PreAuth	/payment/preauth	paymentId, currency, basketId, conversationId, paidPrice, price
Non-3DS PostAuth	/payment/postauth	paymentId, currency, basketId, conversationId, paidPrice, price
Retrieve Payment Result	/payment/detail	paymentId, currency, basketId, conversationId, paidPrice, price

3DS Endpoints

Services	Endpoint	Parameter Order
3DS Initialize	/payment/3dsecure/initialize	paymentId , conversationId
3DS PreAuth Initialize	/payment/3dsecure/initialize/preauth	paymentId, conversationId
3DS Auth	/payment/3dsecure/auth	paymentId, currency, basketId, conversationId, paidPrice, price
3DS v2 Auth	/payment/v2/3dsecure/auth	paymentId, currency, basketId, conversationId, paidPrice, price
3DS PostAuth	/payment/postauth	paymentId, currency, basketId, conversationId, paidPrice, price
Retrieve Payment Result	/payment/detail	paymentId, currency, basketId, conversationId, paidPrice, price

callbackURL Redirection

Services	Parameter Order
callbackURL	conversationData , conversationId, mdStatus, paymentId, status

Checkout Form(CF) & PayWithiyzico(PWI) Endpoints

Services	Endpoint	Parameter Order
CheckoutForm Initialize	/payment/iyzipos/checkoutform/initialize/auth/ecom	conversationId, token
Pay with iyzico Initialize	/payment/pay-with-iyzico/initialize	conversationId, token
CheckoutForm PreAuth Initialize	/payment/iyzipos/checkoutform/initialize/preauth/ecom	conversationId, token
Retrieve Payment Result	/payment/iyzipos/checkoutform/auth/ecom/detail	paymentStatus, paymentId, currency, basketId, conversationId, paidPrice, price, token

Refund Endpoints

Services	Endpoint	Parameter Order
Refund	/payment/refund	paymentId, price, currency, conversationId
Amount Base Refund	/v2/payment/refund	paymentId, price, currency, conversationId

Sample Signature for Non-3DS Endpoint

In this section, we are going to investigate how to extract signature value for a Non-3DS Endpoints payment request, {{baseUrl}}/payment/auth specifically. Sample covers following steps, relatively;

• Payment Request

• Payment Response

• Signature Comparison

So lets begin with Payment Request;

Payment Request

Assuming you have a full request with the variables conversationId, price, paidPrice, currency, and basketId, relatively. Our focus will be on these variables for the signature implementation in the /payment/auth endpoint.

If there is a price parameter among the parameters that make up the signature value, the relevant parameter should be set to trailingZero before the hashString to be encrypted. Please find details below at Trailing Zero section.

POST /payment/auth HTTP/1.1
Host: https://sandbox-api.iyzipay.com
Authorization: IYZWSv2 YOUR_AUTHORIZATION
Content-Type: application/json
{
   ///...
   "conversationId":"conversationId",
   "price":"10.5",
   "paidPrice":"10.5",
   "currency":"TRY",
   "basketId":"basketId",
   ///...
}

Payment Response

Considering that you successfully received a response from the Payment Request above, the expected response payload will be as follows:

{
    "status": "success",
    "locale": "tr",
    "systemTime": "...",
    //...
    "conversationId": "conversationId",
    "price": 10.5,
    "paidPrice": 10.5,
    "paymentId": "22416032",
    "currency": "TRY",
    "basketId": "basketId",
    ///...
    "merchantCommissionRate": "...",
    "merchantCommissionRateAmount": "...",
    "iyziCommissionRateAmount": "...",
    "iyziCommissionFee": "...",
    "cardType": "...",
    "cardAssociation": "...",
    ///...
    "itemTransactions": [
        {
            //...
        }
    ],
    ///...
    "signature": "836c3a6c8db86c81043f2ca74edb13518b54a813f454f8dd762f0dd658610173"
}

We need to focus on conversationId, price, paidPrice, paymentId, currency, and basketId. Even if the entire response covers multiple details, these are the key elements.

Signature Comparison

At last, it is time to check if signatures are matching, for this sample we have used;

• /payment/auth endpoint

• /payment/auth endpoint signature requires, relatively;

  • paymentId

  • currency

  • basketId

  • conversationId

  • paidPrice

  • price variables

So lets check if those matches by the HMAC SHA 256 algorithm;

function generateResponseSignature(params) {
    var dataToEncrypt = params.join(seperator);
    var encryptedData = CryptoJS.HmacSHA256(dataToEncrypt, secretKey);
    var hashedSignature = CryptoJS.enc.Hex.stringify(encryptedData);
    return data;
}

Let's verify if they match using the HMAC-SHA-256 algorithm:

Endpoint: /payment/auth

// Merchant Secret Key
var secretKey: sandbox-qaIiLIxhjMgx3LSKIVvp6j17NunHOFtD

// Seperator must be ":"
var seperator: ":"

// Response Parameters
var paymentId: 22416032
var currency: TRY
var basketId: basketId
var conversationId: conversationId
var paidPrice: 10.5
var price: 10.5

function generateResponseSignature(params) {
    var dataToEncrypt = params.join(seperator);
    // dataToEncrypt: 22416032:TRY:basketId:conversationId:10.5:10.5
    
    var encryptedData = CryptoJS.HmacSHA256(dataToEncrypt, secretKey);
    // encryptedData : 836c3a6c8db86c81043f2ca74edb13518b54a813f454f8dd762f0dd658610173
    
    var hashedSignature = CryptoJS.enc.Hex.stringify(encryptedData);
    // hashedSignature : 836c3a6c8db86c81043f2ca74edb13518b54a813f454f8dd762f0dd658610173
    
    return data;
}

The signature value from response is

• 836c3a6c8db86c81043f2ca74edb13518b54a813f454f8dd762f0dd658610173

hashedSignature value from the method;

• 836c3a6c8db86c81043f2ca74edb13518b54a813f454f8dd762f0dd658610173

Both values are equal, confirming the response from iyzico.

Trailing Zero

In the context of iyzico's response signature validation refer to zeros that appear after the decimal point in price parameters. These trailing zeros need to be included in the validation process to ensure the accuracy of the HMAC SHA256 signature algorithm. For an instance, a price of "price":"50.00" should be treated as "50" during signature creation and validation.

For instance, consider the following values received from the service response;

• "price":"10" after trailing zeros it should be 10

• "price":"10.0" after trailing zeros it should be 10

• "price":"10.5" after trailing zeros it should be 10.5

• "price":"10.50" after trailing zeros it should be 10.5

• "price":"10.510" after trailing zeros it should be 10.51

• "price":"10.5105" after trailing zeros it should be 10.5105

• "price":"10.51050" after trailing zeros it should be 10.5105

Please note that handling trailing zeros is a process that merchants need to address in their codebase before calculating the signature. This function is not directly provided by iyzico.