Kimlik doğrulama

InfraIO Pay’in farklı auth modelleriyle iki API yüzeyi vardır. Kimin çağırdığına uyanı seçin:

Bu sayfa B2B yüzeyini kapsar; bir API anahtar çifti ile sunucunuzdan çağırdığınız yüzey. Panel yüzeyi InfraIO Pay satıcı paneli tarafından kullanılır ve herkese açık bir entegrasyon yüzeyi değildir.

İsteklerde her zaman /b2b öneki dahil tam yolu gönderin ve aynı yolu imzalayın (aşağıya bakın).

Uç noktalar

Aynı URL deseni — ortam, URL ile değil, anahtar öneki ile kontrol edilir (pk_test_… vs pk_live_…).

Anahtar çifti

Satıcı panelinden iki değer alırsınız (Geliştiriciler → API anahtarları → + Anahtar ekle):

• Publishable key (pk_test_… veya pk_live_…) — hesabınızı tanımlar. X-Client-ID olarak gönderilir. Tarayıcı paketinize gömmek güvenlidir (SDK bunu zaten yapar).
• Secret key (sk_test_… veya sk_live_…) — HMAC imzalama anahtarı. Yalnızca sunucu. Bir veritabanı şifresi gibi davranın.

Bir isteği imzalama

/b2b/v1/*’a yapılan her çağrı üç başlık taşır:

X-Client-ID:  pk_live_70d0becbd7a53047b0dfe88a960d10ad
X-Timestamp:  1715990400
X-Signature:  9a8b7c6d…             (hex HMAC-SHA256)

İmza bir kanonik dize üzerinde hesaplanır:

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY

• METHOD — büyük harf HTTP fiili (POST, GET, …).
• PATH — host olmadan ve query string olmadan, /b2b öneki dahil istek yolu (örn. /b2b/v1/checkout-sessions/quick). Önek mevcut olmalıdır. Query parametreleri imzalanmaz — bir GET …?cursor=…&limit=20 için yalnızca yolu imzalayın, ?… kısmını değil.
• TIMESTAMP — unix saniye, ondalık string olarak (örn. "1715990400"), X-Timestamp ile tam olarak eşleşmelidir.
• BODY — ham istek gövdesi baytları. GET/DELETE için boş string.

Secret anahtarla HMAC-SHA256 ile imzalayın, çıktı hex:

import { createHmac } from "node:crypto";
 
function sign({ method, path, body, secret }: {
  method: string; path: string; body: string; secret: string;
}) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const input = [method.toUpperCase(), path, timestamp, body].join("\n");
  const signature = createHmac("sha256", secret).update(input).digest("hex");
  return { timestamp, signature };
}

package infraio
 
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strconv"
    "time"
)
 
func Sign(method, path, body, secret string) (timestamp, signature string) {
    timestamp = strconv.FormatInt(time.Now().Unix(), 10)
    input := method + "\n" + path + "\n" + timestamp + "\n" + body
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(input))
    return timestamp, hex.EncodeToString(mac.Sum(nil))
}

import hmac, hashlib, time
 
def sign(method: str, path: str, body: str, secret: str):
    timestamp = str(int(time.time()))
    input_ = f"{method}\n{path}\n{timestamp}\n{body}"
    signature = hmac.new(
        secret.encode(), input_.encode(), hashlib.sha256
    ).hexdigest()
    return timestamp, signature

Neden HMAC, Bearer değil?

Bir çıplak Bearer-token API’si, her istekte tek secret’ınızı tel üzerinden gönderir. Bir TLS-sonlandırılmış proxy logu yakalayan herkes hesabınızın anahtarlarını alır. HMAC imzalama, secret’ın asla seyahat etmediği anlamına gelir — yalnızca türetilmiş imzası, ki bu da tek kullanımlıktır (o tam isteğe + o tam dakikaya bağlı).

Ödünleşim: her çağrı için bir imza hesaplarsınız. Henüz bir sunucu SDK’sı yok, ancak yukarıdaki yardımcı dil başına yaklaşık 15 satırdır.

Timestamp toleransı

Tolerans ±5 dakikadır (300 saniye). Bu pencerenin dışındaki bir istek 401 invalid_signature ile reddedilir. İki sonuç:

1. Sunucu saatinizi NTP ile senkronize edin. Kaymış saatli uzun süre çalışan bir cron aralıklı olarak başarısız olur.
2. İmzaları önceden hesaplayıp kuyruğa almayın. Bir istek bir yeniden deneme kuyruğunda >5 dakika oturursa, imzasının süresi dolar.

Anahtar scope’ları

Secret anahtarlar şu scope demetlerinden bir veya daha fazlasını taşır:

Panel varsayılan olarak bir “tam erişim” anahtarı verir (dört scope da). Entegrasyonun ihtiyaç duyduğu scope’ları işaretleyerek Geliştiriciler → API anahtarları → + Anahtar ekle üzerinden kısıtlı scope’lu bir anahtar üretebilirsiniz.

Başarısız doğrulama

İmza, X-Client-ID veya timestamp geçersizse istek, API’ye ulaşmadan 401 INVALID_SIGNATURE ile reddedilir. Yalnızca /b2b/v1/* istekleri bu şekilde imzalanır. Webhook’lar ayrı bir şema kullanır (aşağıya bakın).

Sırada ne var

• Hatalar — 4xx/5xx’te yanıt şekli.
• Güvenlik → API anahtarları — rotation, iptal, bir secret sızarsa ne yapılacağı.
• Webhook’lar → İmza doğrulama — farklı bir HMAC şeması kullanır (X-Signature: sha256=… başlığı, X-Timestamp + "." + raw_body imzalar, artı 24 saatlik rotation kayma penceresinde opsiyonel bir X-Signature-Prev). Şemaları karıştırmayın — hash algoritmasını paylaşırlar ama imzalanan baytlar ve secret ailesi (whsec_… vs sk_…) farklıdır.