İmza Yanıtının Doğrulanması

Bu sayfa, iyzico'nun API'sini kullanarak İmza Yanıtının Doğrulanmasının uygulanmasına ilişkin ayrıntılı rehberlik sağlamak amacıyla hazırlanmıştır. İmza Yanıtının Doğrulanması, özellikle finansal işlemlerde işyerleri ile iyzico arasında alınıp verilen verilerin doğruluğunun ve bütünlüğünün sağlanması açısından önemlidir. Geliştiriciler, HMAC SHA256 imzalarını oluşturma ve doğrulama talimatlarını izleyerek uygulamalarını üçüncü parti kişilerin müdahalesinden ve yetkisiz erişime karşı koruyabilirler. Bu, işlem sürecinin genel güvenliğini artırarak hem satıcıları hem de müşterileri korur.

Genel Özet

signature parametresi, hizmet yanıtını doğrulamak için belirli yanıt parametreleri ile satıcının gizli anahtarı (secretKey) kullanılarak dorulanır. Bununla birlikte, satıcı ile iyzico arasındaki hizmet güvenliği HMAC SHA256 kullanarak arttırılır.

signature aşağıdaki endpointler'de bulunmaktadır;

• Non-3DS Endpoints

• 3DS Endpoints

• "callbackUrl" Redirection

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

signature değeri, iyzico API yanıtlarından gelen parametreler kullanılarak oluşturulmalıdır.

Non-3DS Endpointleri

Servisler	Endpoint	Parametre Sıralaması
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
Ödeme Sonucunu Alma	/payment/detail	paymentId, currency, basketId, conversationId, paidPrice, price

3DS Endpointleri

Servisler	Endpoint	Parametre Sıralaması
3DS Başlatma	/payment/3dsecure/initialize	paymentId , conversationId
3DS PreAuth Başlatma	/payment/3dsecure/initialize/preauth	paymentId, conversationId
3DS Auth	/payment/3dsecure/auth	paymentId, currency, basketId, conversationId, paidPrice, price
3DS PostAuth	/payment/postauth	paymentId, currency, basketId, conversationId, paidPrice, price
Ödeme Sonucunu Alma	/payment/detail	paymentId, currency, basketId, conversationId, paidPrice, price

callbackURL Yönlendirmesi

Servisler	Parametre Sıralaması
callbackURL	conversationData , conversationId, mdStatus, paymentId, status

Checkout Form(CF) & PayWithiyzico(PWI) Endpointleri

Servisler	Endpoint	Parametre Sıralaması
CheckoutForm Başlatma	/payment/iyzipos/checkoutform/initialize/auth/ecom	conversationId, token
iyzico ile Öde Başlatma	/payment/pay-with-iyzico/initialize	conversationId, token
CheckoutForm PreAuth Başlatma	/payment/iyzipos/checkoutform/auth/ecom/detail	paymentStatus, paymentId, currency, basketId, conversationId, paidPrice, price, token
Ödeme Sonucunu Alma	/payment/iyzipos/checkoutform/initialize/preauth/ecom	conversationId, token

Non-3DS Endpoint'i İçin Signature Örneği

Bu bölümde, Non-3DS Endpoints ödeme isteği için signature değerinin nasıl çıkarılacağını {{baseUrl}}/payment/auth endpoint'i özelinde anlatacağız. Örnek yapımız, aşağıdaki adımları kapsamaktadır;

• Ödeme İsteği

• Ödeme Yanıtı

• İmza Karşılaştırması

Ödeme isteği ile başlayalım;

Ödeme İsteği

conversationId, price, paidPrice, currency, ve basketIdkullanarak bir istek attığınızı varsayalım. Odak noktamız, bu değerleri, /payment/auth endpoint'ini kullanarak imza oluşumunda nasıl uygulandığını görebilmektir.

Eğer price parametresi signature değerini oluşturan parametreler arasında bulunuyorsa, ilgili değer, hashString ile şifrelenmeden önce trailingZero olarak ayarlanmaktadır. Bu konudaki detaylı bilgili Trailing Zero kısmında bulabilirsiniz.

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",
   ///...
}

Ödeme İsteği Yanıtı

Yukarıdaki Ödeme İsteği'nden başarıyla bir yanıt aldığınızı göz önünde bulundurarak, beklenen yanıt verisi aşağıdaki gibi olacaktır:

{
    "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"
}

Burada conversationId, price, paidPrice, paymentId, currency, ve basketIdparametrelerine odaklanmalıyız. Yanıtın tamamı bu parametrelerden dışındaki ayrıntıları kapsasa bile bunlar temel unsurlardır.

İmza Karşılaştırması

Son olarak sıra imzaların eşleşip eşleşmediğini kontrol etmeye geldi, kullandığımız bu örnek için;

• /payment/auth endpointi

• /payment/auth endpointi signature oluşturmak için gereken parametreler;

  • paymentId

  • currency

  • basketId

  • conversationId

  • paidPrice

  • price değişkenleridir.

Şimdi bunların eşleşip eşleşmediğini HMAC-SHA-256 algoritmasıyla kontrol edelim;

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

HMAC-SHA-256 algoritmasını kullanarak eşleşip eşleşmediklerini doğrulayalım:

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;
}

Yanıttan dönen signature değeri;

• 836c3a6c8db86c81043f2ca74edb13518b54a813f454f8dd762f0dd658610173

Kullandığımız yöntemden gelen hashedSignature değeri;

• 836c3a6c8db86c81043f2ca74edb13518b54a813f454f8dd762f0dd658610173

Her iki değerin de eşit olması, yanıtın iyzico'dan geldiğini doğruluyor.

Ardıl Sıfırlar(Trailing Zero)

iyzico'nun yanıt imzası doğrulaması bağlamında, fiyat parametrelerinde ondalık noktadan sonra görünen sıfırlara atıfta bulunur. Bu ardıl sıfırların doğrulama sürecine dahil edilmesi, HMAC SHA256 imza algoritmasının doğruluğunu sağlamak için gereklidir. Örnek vermek gerekirse, "price":"50.00" fiyatı, imzanın yaratılmasında ve doğrulanmasında "50" olarak ele alınmalıdır.

Örneğin servis yanıtından alınan aşağıdaki değerleri göz önünde bulundurun;

• "price":"10" ardıl sıfırların atılmasından sonra 10 olmalıdır

• "price":"10.0" ardıl sıfırların atılmasından sonra 10 olmalıdır

• "price":"10.5" ardıl sıfırların atılmasından sonra 10.5 olmalıdır

• "price":"10.50" ardıl sıfırların atılmasından sonra 10.5 olmalıdır

• "price":"10.510" ardıl sıfırların atılmasından sonra 10.51 olmalıdır

• "price":"10.5105" ardıl sıfırların atılmasından sonra 10.5105 olmalıdır

• "price":"10.51050" ardıl sıfırların atılmasından sonra10.5105olmalıdır

Sondaki sıfırların atılmasının, satıcıların imzayı hesaplamadan önce kod tabanlarında ele almaları gereken bir süreç olduğunu lütfen unutmayın. Bu işlev doğrudan iyzico tarafından sağlanmamaktadır.