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 // x-iyzi-rnd used to be random key from previous SHA1 Authentication
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. (x-iyzi-rnd used to be random key from previous SHA1 Authentication)
encryptedData: The encrypted version of the request payload parameters with HMACSHA256.
Authentication can be divided into three sequential steps:
encryptedData
base64Encoded
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(randomKey + uri.path + request.body, 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
// x-iyzi-rnd used to be random key from previous SHA1 Authentication, so plese do not hesitate to use x-iyzi-rnd as your randomkey.
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);
Last updated