Kimlik Doğrulama ve İmza

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

X-Api-Key: key_...
X-Signature: <ham gövdenin HMAC-SHA256 imzası, küçük harf hex>
Content-Type: application/json

Başlık	Değer
X-Api-Key	Çalışma alanının API anahtarı.
X-Signature	Gövdenin ham metninin, gizli anahtarla alınan HMAC-SHA256 özeti; küçük harfli hex.
Content-Type	application/json

SDK'lar ayrıca Accept: application/json gönderir.

İmza

X-Signature = lowercase_hex( HMAC_SHA256( key = gizli_anahtar, message = ham_gövde ) )

• İmza gövdenin tamamını, byte byte kapsar. Alan listesi ya da sıralama kuralı 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.
• Gateway'in yanıtları ve abonelik webhook'ları aynı yöntemle, aynı gizli anahtarla imzalanır ve imza X-Signature başlığında gelir.

Test vektörü:

Gizli anahtar	Gövde	İmza
secret_test	{"a":1}	6d0c951564cdd2b6b70e75b214293a8cd2542815ba54fe91c7f6ce105bc3d592

İsteği imzalamak

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

PHP

$body = json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
$signature = hash_hmac('sha256', $body, getenv('ODEMEHUB_API_SECRET'));

// $body'yi olduğu gibi gönderin.

Node.js

import { createHmac } from 'node:crypto';

const body = JSON.stringify(payload);
const signature = createHmac('sha256', process.env.ODEMEHUB_API_SECRET!).update(body).digest('hex');

// body'yi olduğu gibi gönderin.

Python

import hashlib
import hmac
import json
import os

body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()
signature = hmac.new(os.environ["ODEMEHUB_API_SECRET"].encode(), body, hashlib.sha256).hexdigest()

# body'yi olduğu gibi gönderin.

Java

import com.odemehub.Signature;

byte[] body = objectMapper.writeValueAsBytes(payload);
String signature = new Signature(System.getenv("ODEMEHUB_API_SECRET")).sign(body);

// body'yi olduğu gibi gönderin.

cURL

BODY='{"transaction":{"token":"0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d"}}'
SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')

curl -X POST "https://odeme.gurmehub.com/api/$ODEMEHUB_TEAM/gateway/retrieve-payment" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: $ODEMEHUB_API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

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

200 yanıtları imzalıdır. Gövdeyi ham hâliyle okuyun, aynı yöntemle imzasını 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.

PHP

use Gurmehub\Odemehub\Signature;

// SDK her 200 yanıtını kendisi doğrular; tutmazsa SignatureException atar.
$valid = (new Signature(getenv('ODEMEHUB_API_SECRET')))->verify($rawBody, $signatureHeader);

Node.js

import { Signature } from '@odemehub/node-sdk';

// SDK her 200 yanıtını kendisi doğrular; tutmazsa SignatureError atar.
const valid = new Signature(process.env.ODEMEHUB_API_SECRET!).verify(rawBody, signatureHeader);

Python

import os

from odemehub import Signature

# SDK her 200 yanıtını kendisi doğrular; tutmazsa SignatureError atar.
valid = Signature(os.environ["ODEMEHUB_API_SECRET"]).verify(raw_body, signature_header)

Java

import com.odemehub.Signature;

// SDK her 200 yanıtını kendisi doğrular; tutmazsa SignatureException atar.
boolean valid = new Signature(System.getenv("ODEMEHUB_API_SECRET")).verify(rawBody, signatureHeader);

cURL

# Gövde response.json'da, başlıklar headers.txt'de
EXPECTED=$(openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" < response.json | sed 's/^.* //')
RECEIVED=$(grep -i '^x-signature:' headers.txt | awk '{print $2}' | tr -d '\r')
[ "$EXPECTED" = "$RECEIVED" ] && echo "imza geçerli" || echo "imza geçersiz"

Kimlik doğrulama hataları

Her iki durumda da yanıt 401'dir ve imzasızdır.

Durum	result.message
X-Api-Key eksik ya da adresteki çalışma alanına ait değil	Geçersiz API anahtarı.
X-Signature eksik ya da gövdeyle tutmuyor	İmza doğrulanamadı.

{
  "result": {
    "successful": false,
    "message": "İmza doğrulanamadı."
  }
}