Ana içeriğe geç

Kimlik Doğrulama ve İmza

Her istek üç başlıkla kimlik doğrular:

X-Api-Key: key_...
X-Timestamp: 1790932530
X-Signature: <imza, küçük harf hex>
Content-Type: application/json
BaşlıkDeğer
X-Api-KeyÇalışma alanının API anahtarı.
X-Timestampİmzanın atıldığı an, Unix saniyesi (yalnızca rakam). Sunucu saatinden en fazla 5 dakika uzak olabilir.
X-Signatureİmzalanan metnin gizli anahtarla alınan HMAC-SHA256 özeti; küçük harfli hex.
Content-Typeapplication/json (gövdeli isteklerde).

İmza​

imzalanan_metin = "{timestamp}\n{METOT}\n{yol}\n{gövde}"
X-Signature = lowercase_hex( HMAC_SHA256( key = gizli_anahtar, message = imzalanan_metin ) )
ParçaDeğer
timestampX-Timestamp başlığında gönderilen değerin aynısı.
METOTBüyük harfle HTTP metodu. Gateway uçlarının hepsi POST'tur.
yolAdresin / ile başlayan, sorgu dizesi olmayan yolu: /api/4829301756/gateway/regular-payment. Alan adı dahil edilmez.
gövdeGönderilen gövdenin ham metni, byte byte. Alanı olmayan bir istekte (ör. son 7 günü soran retrieve-*) {} gönderilir ve imzalanır.
  • Parçalar tek bir satır sonuyla (\n) birleştirilir; sonda fazladan satır sonu yoktur.
  • Gövdeyi bir kez metne çevirin; aynı metni hem imzalayın hem gönderin. İmzadan sonra gövdeyi yeniden kodlayan bir katman (boşluk, alan sırası, Unicode ya da / kaçışı) imzayı bozar. Alan sırası ve boşluk, imzalanan ve gönderilen metin aynı olduğu sürece önemli değildir.
  • İmza yol ve metodu kapsadığı için bir uç için imzalanmış istek başka bir uca gönderilemez; zaman damgası 5 dakikadan eski istek kabul edilmez.

Test vektörü:

Gizli anahtarZaman damgasıMetotYolGövdeİmza
secret_test1700000000POST/api/1000000001/gateway/regular-payment{"a":1}4d6225c9dd46837418b40dd8140d76a24cd7520d81ff3b280bf98da8da6a8771

İsteği imzalamak​

SDK'lar bu adımı kendileri yapar. SDK kullanmadan:

$path = '/api/'.getenv('ODEMEHUB_TEAM').'/gateway/regular-payment';
$body = json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
$timestamp = (string) time();
$signature = hash_hmac('sha256', "{$timestamp}\nPOST\n{$path}\n{$body}", getenv('ODEMEHUB_API_SECRET'));

// $body'yi olduğu gibi gönderin; X-Timestamp: $timestamp, X-Signature: $signature

Yanıtın imzasını doğrulamak​

Gateway'in 200, 403, 404, 422, 429 ve 500 yanıtları imzalıdır (401 ve çalışma alanı bulunamadığında dönen 404 imzasızdır). Yanıt kendi X-Timestamp ve X-Signature başlıklarıyla gelir; imzalanan metin, isteğin metodu ve yolu ile yanıtın ham gövdesinden kurulur:

"{yanıtın X-Timestamp değeri}\n{isteğin METODU}\n{isteğin yolu}\n{yanıtın ham gövdesi}"

Gövdeyi ham hâliyle okuyun, imzayı hesaplayın ve X-Signature başlığıyla sabit zamanlı karşılaştırın. Tutmuyorsa yanıtı işlemeyin.

not

Gateway yanıt gövdesinde / karakterini \/ olarak kaçışlar (ör. "https:\/\/..."). İmza bu ham metin üzerinden hesaplanır; gövdeyi ayrıştırıp yeniden yazmadan doğrulayın.

use Gurmehub\Odemehub\Signature;

// SDK her yanıtı kendisi doğrular; tutmazsa SignatureException atar.
$valid = (new Signature(getenv('ODEMEHUB_API_SECRET')))->verify(
'POST', $path, $rawResponseBody, $responseTimestampHeader, $responseSignatureHeader,
);

SDK'ların verify yardımcıları, zaman damgası 5 dakikadan eski olan imzayı da geçersiz sayar.

Kimlik doğrulama hataları​

Yanıt 401'dir ve imzasızdır.

Durumresult.message
X-Api-Key eksik ya da adresteki çalışma alanına ait değilGeçersiz API anahtarı.
X-Timestamp eksik, rakam dışı karakter içeriyor ya da 5 dakikadan uzakİmzanın zaman damgası eksik ya da izin verilen aralığın dışında.
X-Signature eksik ya da imzalanan metinle tutmuyorİmza doğrulanamadı.
{
"result": {
"successful": false,
"message": "İmza doğrulanamadı."
}
}

Sunucunuzun saati kaymışsa bütün istekler zaman damgası hatası alır; saati NTP ile eşitleyin.