1000pay API’leri, tekrarlanan taleplerde tutarlı ve güvenli bir işlem davranışı sağlamak üzere, kimlik doğrulama ve imza üretimi merkezli bir mimariyle tasarlanmıştır. Üye işyerlerinin gerçekleştirdiği tüm API çağrıları, talebin kaynağını ve bütünlüğünü doğrulamak amacıyla belirli parametrelerin birlikte kullanılmasını gerektirir.Bu kapsamda; Public/Private Key, nonce, signature, conversationId, merchantNumber ve clientIpAddress gibi alanlar, hem güvenlik hem de izlenebilirlik açısından kritik rol oynar. Aşağıdaki bölümlerde, bu parametrelerin her biri ile 1000pay ödeme servislerinin REST tabanlı mimarisi detaylı şekilde açıklanmaktadır.
Bir üye işyerine ait hesapla gerçekleştirilen tüm API çağrıları kimlik doğrulama gerektirir. Bir isteğin geçerli kabul edilebilmesi için aşağıdaki parametrelerin eksiksiz olarak iletilmesi zorunludur:
Üye işyeriniz sisteme tanımlandıktan sonra, entegrasyonlarda kullanılmak üzere size bir Public Key ve bir Private Key verilir.
Public Key, API çağrılarında kimliğinizi tanımlamak için kullanılır.
Private Key, yalnızca size özeldir ve güvenlik nedeniyle hiçbir koşulda paylaşılmamalıdır.
1000pay tarafından sunulan hiçbir API, Private Key bilgisini açık şekilde talep etmez. Bu anahtar yalnızca imza (signature) üretiminde kullanılmalıdır.
Nonce, her API isteği için üye işyeri tarafından üretilen sayısal bir değerdir ve genellikle milisaniye cinsinden zaman damgasını temsil eder.Bu değer, aynı isteğin tekrar gönderilmesini önlemek ve işlem güvenliğini artırmak amacıyla kullanılır.
Signature, API isteğinin güvenliğini sağlamak için kullanılan HMAC-SHA256 algoritmasıyla üretilen bir imza değeridir.Bu değer; nonce (zaman damgası), API anahtarları ve işleme ait bazı bilgilerin kullanılmasıyla iki aşamalı hashleme süreci sonucunda oluşturulur. Signature üretimine ait örnek kod, Şekil 5.1’de gösterilmektedir.
Copy
using System;using System.Security.Cryptography;using System.Text;public class SignatureUtil{ public static string GenerateSignature( string publicKey, string privateKeyBase64, string conversationId, long nonce ) { var message = $"{publicKey}{nonce}"; var securityData = Generate(message, privateKeyBase64); var secondMessage = $"{privateKeyBase64}{conversationId}{nonce}{securityData}"; return Generate(secondMessage, privateKeyBase64); } private static string Generate(string message, string key) { using var hmac = new HMACSHA256(Convert.FromBase64String(key)); var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message)); return Convert.ToBase64String(hash); }}
Signature üretimi iki aşamalı bir süreçtir:İlk aşamada, Public Key ile nonce değeri birleştirilir ve ortaya çıkan mesaj, üye işyerine ait Private Key kullanılarak hashlenir. Bu işlem sonucunda 1. seviye güvenlik verisi elde edilir.İkinci aşamada ise; Private Key, conversationId, nonce ve 1. seviye güvenlik verisi bir araya getirilir. Bu değer tekrar Private Key ile hashlenerek nihai signature oluşturulur.Oluşturulan signature ve ilgili diğer kimlik doğrulama parametreleri, tüm API isteklerinde header alanında gönderilmelidir. Sunucu, bu bilgileri kullanarak isteğin doğruluğunu ve kaynağını kontrol eder ve doğrulama başarılıysa isteği işleme alır. Header yapısına ait örnek Şekil 5.2’de gösterilmektedir.
ConversationId, üye işyerinin API isteği sırasında gönderdiği ve aynı şekilde yanıt içinde geri alabildiği bir referans değeridir.İstek ve yanıtların birbiriyle eşleştirilmesini sağlar. En yaygın kullanım senaryosu, bu alanın üye işyerine ait sipariş numarası olarak kullanılmasıdır.
Merchant Number, üye işyerinin 1000pay sistemine tanımlanmasının ardından kendisine verilen benzersiz tanımlayıcı numarayı ifade eder.API çağrılarında, işlemin hangi üye işyerine ait olduğunu belirtmek amacıyla kullanılır.
ClientIpAddress, üye işyerinin müşterisine ait IP adresini ifade eder. Bu bilgi, işlem güvenliği, risk analizi ve loglama amaçlarıyla API çağrılarında iletilir.
1000Pay Ödeme servisleri; tüm yazılımlara entegre olarak çalışabilecek bir mimaride, REST servisler şeklinde implemente edilmiştir. PF servislerimizin Open API dokümantasyonuna aşağıdaki adresten ulaşılabilir.1000pay Test Swagger
