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;

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

Non-3DS Endpoints

ServicesEndpointParameter 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

ServicesEndpointParameter 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

ServicesParameter Order

callbackURL

conversationData , conversationId, mdStatus, paymentId, status

Checkout Form(CF) & PayWithiyzico(PWI) Endpoints

ServicesEndpointParameter 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

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.

Last updated