HMACSHA256 Auth

Authentication for iyzico services aligns with Basic Auth principles, while enhancing security through a precise sequence of encryption techniques, including PKI string, Base64, HMAC and SHA-256 hashing

To access our API securely, authentication is required. Authentication is achieved through the inclusion of an API Key and base64EncodedAuthorization together in the header of your HTTP requests.

"Authorization": "IYZWSv2"+" "+"base64EncodedAuthorization"

Example Request Header:

POST /payment/bin/check HTTP/1.1
Host: sandbox-api.iyzipay.com
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib3gtbDlNZDFHajNJWWNtdTROZGFXeGFTVW9Db1g3REM1UkEmcmFuZG9tS2V5OjEyMzQ1Njc4OSZzaWduYXR1cmU6MDc5ZGY0YjI0MjZmYzdmNDIwOGQ4ZjIyZmJjMDM0OTc5NDAxOWY4Y2UyYjA3MTFkZTc4MDhiNDg3NGY0ZTc5Ng==
Content-Type: application/json
x-iyzi-rnd: 123456789

Overview

Here's a breakdown of the required components:

• apiKey: Your unique API key assigned to your account.

• secretKey: Your secret key associated with your account.

• x-iyzi-rnd: A randomly generated number by merchants that included in the request header for each API call.

• encryptedData: The encrypted version of the request payload parameters with HMACSHA256.

Authentication can be divided into three sequential steps:

1. encryptedData

2. base64Encoded

3. Authorization

1. encryptedData

The encryptedData represents a encrypted version of the request payload, the process entails generating a hash using HMACSHA256 encryption.

The signature is generated using the following formula, relatively;

HMACSHA256(request.header.randomKey + request.payload, secretKey)

With in a sample, below you may find a dummy Bin Check request curl;

curl 
--location --request POST 'https://api.iyzipay.com/payment/bin/check' \
--header 'Authorization: IYZWSv2 ***' \
--header 'x-iyzi-rnd: 123456789' \
--header 'Content-Type: application/json' \
--data-raw '{
    "locale":"tr",
    "binNumber":"535805",
    "conversationId": "docsTest-v1"
}'

encryptedData for that Bin Check request above is;

079df4b2426fc7f4208d8f22fbc0349794019f8ce2b0711de7808b4874f4e796

2. base64Encoded

Assuming that the encryptedData has been generated correctly, it is now time for Base64 encryption.

The signature is generated using the following formula, relatively;

base64("apiKey:"+apiKey+"&randomKey:"+randomKey+"&signature:"+encryptedData)

The result is our base64EncodedAuthorization to be used in the header.

3. Authorization

After all the operations, the final and simplest step is to include IYZWSv2, base64EncodedAuthorization in the header, relatively.

...
"Authorization": "IYZWSv2"+" "+"base64EncodedAuthorization"
...

In between IYZWSv2 and base64EncodedAuthorization there is a single line space.

Sample Pre-request Script of Authorization on Postman

Taking a dummy Bin Check request as an example, the authorization process would be as follows;

var apiKey = environment.apiKey;
var secretKey = environment.secretKey;
 
//Generate authorization string
function generateAuthorizationString() {

    // Lets create uniq randomKey
    // Sample randomKey : 1722246017090123456789
    var randomKey = new Date().getTime() + "123456789";
    
    // Get the uri path for this request
    // Sample uri_path : /payment/bin/check
    var uri_path = "/payment/bin/check";
    
    // Get the payload and concatanete with uri path and randomKey.
    // Sample payload : payload: 1722246017090123456789/payment/bin/check{"binNumber":"589004"}
    var payload = _.isEmpty(request.data) ? randomKey + uri_path : randomKey + uri_path + request.data;
    
    // Encrypt the payload with HMACSHA256
    // Sample encryptedData : 91e491486d3aa951b4f387cc93d67fc754c4729af95344b694435f56447819e9
    var encryptedData = CryptoJS.HmacSHA256(payload, secretKey);
 
    // Create the authorizationString using encryptedData
    /* Sample authorizationString : apiKey:sandbox-3uHv0LccjcWDyFHTvJpiACKPcJwbczmZ&
                                        randomKey:1722246017090123456789&
                                        signature:91e491486d3aa951b4f387cc93d67fc754c4729af95344b694435f56447819e9 */
    var authorizationString = "apiKey:" + apiKey
                        + "&randomKey:" + randomKey
                        + "&signature:" + encryptedData;
    
 
    // Encode the authorizationString with base64 
    // Sample base64EncodedAuthorization : YXBpS2V5OnNhbmRib3gtM3VIdjBMY2NqY1dEeUZIVHZKcGlBQ0tQY0p3YmN6bVomcmFuZG9tS2V5OjE3MjIyNDYwMTcwOTAxMjM0NTY3ODkmc2lnbmF0dXJlOjkxZTQ5MTQ4NmQzYWE5NTFiNGYzODdjYzkzZDY3ZmM3NTRjNDcyOWFmOTUzNDRiNjk0NDM1ZjU2NDQ3ODE5ZTk=
    var base64EncodedAuthorization = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(authorizationString));
 
    // Concatanate the encoded authorizationString with 'IYZWSv2 '.
    // Sample return value : IYZWSv2 YXBpS2V5OnNhbmRib3gtM3VIdjBMY2NqY1dEeUZIVHZKcGlBQ0tQY0p3YmN6bVomcmFuZG9tS2V5OjE3MjIyNDYwMTcwOTAxMjM0NTY3ODkmc2lnbmF0dXJlOjkxZTQ5MTQ4NmQzYWE5NTFiNGYzODdjYzkzZDY3ZmM3NTRjNDcyOWFmOTUzNDRiNjk0NDM1ZjU2NDQ3ODE5ZTk=
    return "IYZWSv2 " + base64EncodedAuthorization;
}
var authorization = generateAuthorizationString();
postman.setEnvironmentVariable("authorization", authorization);