Geliştirici belgeleri

Ödeme bildirimi imzasını doğrulama

Zaman damgası ve ham Webhook gövdesi üzerinden HMAC-SHA256 doğrulaması yapın. HTTP 2xx yanıtından önce zamanı, siparişi ve yinelenen işlemleri kontrol edin.

Bu sipariş API'leri (oluşturma, sorgulama ve yeniden gönderme) HMAC-SHA256 imzalarını kullanır. GET /api/v1/ping yalnızca bir API Anahtarı gerektirir. Ödeme geri aramaları ayrıca bir imza içerir. HMAC, API Anahtarınızı değil satıcınızın Webhook sırrını kullanır.

01. Başlık Özellikleri

01. API sipariş istekleri gönderiliyor

Client to Server

Oluşturma, sorgulama ve yeniden gönderme istekleri ayrıca X-Bolt-Key gerektirir. timestamp, sunucu saatinden 5 dakika uzakta olmalıdır. Yeniden denediğinizde yeni bir timestamp ve imza oluşturun.

Unix milisaniye timestampGerekli
X-Bolt-Timestamp
HMAC-SHA256 onaltılı imzaGerekli
X-Bolt-Signature

02. Ödeme geri aramalarını alma

Server to Merchant

BoltUtil, geri arama zaman damgaları ve imzalar oluşturur. Alıcılar ham gövdeyi doğrulamalı, timestamp penceresini kontrol etmeli ve olayları ve iş emirlerini anında ele almalıdır.

Unix milisaniye timestampGerekli
X-Bolt-Webhook-Timestamp
HMAC-SHA256 onaltılı imzaGerekli
X-Bolt-Webhook-Signature

02. İmza Hesaplaması

1

İmzalı içeriği oluşturma

Başlıktaki zaman damgasını, bir noktayı ve tam ham gövdeyi birleştirin: timestamp + "." + raw_body. UTF-8 kullanın; gövde boş olsa bile noktayı koruyun.

// 1. Construct payload: timestamp + "." + body
String payload = timestamp + "." + body;
2

HMAC-SHA256'yi hesapla

Satıcı Webhook yapılandırmanızdaki gizli bilgiyi kullanın. İmzalama için kullanılan metin, API isteğinizde gönderilen metinle tam olarak eşleşmelidir.

// JDK standard library: javax.crypto.Mac and SecretKeySpec
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] hash = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
3

Küçük harf onaltılı olarak kodlayın

32 baytlık özeti 64 küçük harfli onaltılık karakter olarak kodlayın. API isteklerinde X-Bolt-Signature içinde gönderin. Bildirimleri X-Bolt-Webhook-Signature ile sabit zamanlı karşılaştırma kullanarak doğrulayın.

// JDK 17+: java.util.HexFormat
String signature = HexFormat.of().formatHex(hash);

03. Doğrulama Notları

  • Doğrulamadan önce JSON'yi ayrıştırmayın ve yeniden serileştirmeyin. Boşluk, satır sonları, anahtar sırası ve kodlamanın tümü imzayı etkiler.
  • HMAC içerik bütünlüğünü doğrular ancak tek başına yeniden oynatmayı engellemez. timestamp'nin güncelliğini kontrol edin ve etkinlikleri tekilleştirin.
  • Geçerli bir imza, yerine getirme işleminin tamamlandığı anlamına gelmez. Sipariş ilişkisini, ödeme durumunu, tutarları, para birimini ve ödeme türünü kontrol edin.
Geri arama işlemini görüntüleyin →
signature / cURL
# Calculate a request signature without sending a request.
# BOLTUTIL_WEBHOOK_SECRET is your merchant Webhook secret, not API Key.
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')
printf 'X-Bolt-Timestamp: %s\nX-Bolt-Signature: %s\n' "$timestamp" "$signature"
# Send this SAME body with the above headers and X-Bolt-Key.
# Callback header names are X-Bolt-Webhook-Timestamp and
# X-Bolt-Webhook-Signature. Verify raw bytes before parsing JSON.

Adresler, işlem karmaları ve siparişler örnektir. Bunları kendi testiniz data ile değiştirin.

Base URL

PROD
https://api.boltutil.com