Developers

Webhook'lar

Bir webhook size bir siparişin durum değiştirdiğini söyler. Siparişi okumanın yerini tutmaz: bir bildirimdir, gerçeğin kaynağı değildir.

Yayınlanmış sözleşme, henüz açık değil

Webhook'lar bugün yayınlanmıyor. Şekilleri, imzaları ve yeniden deneme politikaları burada kararlaştırıldı ve yayınlandı, böylece alıcınız önceden yazılıp test edilebilir.

Olaylar

Her olay aynı zarfa sahiptir: bir kimlik, bir tür, bir zaman damgası ve bir veri nesnesi. İşlediğiniz türlere abone olun ve geri kalanını sessizce yok sayın — yeni türler eklenecektir ve bilinmeyen bir türde başarısız olan bir alıcı kendini bozar.

Olaylar
Tür	Anlamı
`order.created`	Sipariş oluşturulur ve kur sabitlenir. Yatırma adresi atanır.
`order.deposit_detected`	Ağda, onaydan önce gelen bir işlem görülür. Bu olayı kullanıcıyı rahatlatmak için kullanın, asla bir şey teslim etmek için değil.
`order.confirming`	Onay sayacı ilerliyor. Her blokta değil, her adımda yayınlanır.
`order.deposit_confirmed`	Ağın gerektirdiği onay sayısına ulaşıldı.
`order.underpaid`	Alınan tutar, toleransın ötesinde beklenen tutarın altında. Sipariş kaybolmadı: ekleme yapma, alınan tutarla devam etme veya iade arasında bir seçim bekliyor.
`order.overpaid`	Alınan tutar beklenen tutarı aşıyor. İlk tutar sabitlenen kurda kalır; fazlalık ayrıca ele alınır.
`order.payout_sent`	Transfer hatta çıktı. Dikkat: gönderildi, alındı anlamına gelmez — kalan gecikme, lehdarın bankasına bağlıdır.
`order.completed`	Ödeme, hat tarafından onaylandı. Terminal durum.
`order.payout_failed`	Hat, transferi nedeniyle reddetti veya iade etti. Banka iadesinde otomatik yeniden deneme yapılmaz: neden neredeyse her zaman ayrıntılardadır.
`order.refunded`	Fonlar, yalnızca gönderen adrese, ağ ücretleri düşülerek iade edildi.

Yük

Tür ne olursa olsun sabit bir zarf.

Örnekjson

{
  "id": "evt_01J9ZQF3K8N2M4X7",
  "type": "order.payout_sent",
  "created": 1788356981,
  "data": {
    "reference": "K7Q4-M2XB",
    "state": "PAYOUT_SENT",
    "railId": "sepa_instant",
    "netMinor": 91228,
    "currency": "EUR",
    "sentAt": "2026-09-02T12:21:44Z"
  }
}

İmza

Her teslimat bir imza başlığı taşır: bir zaman damgası ve bu zaman damgası, bir nokta ve HAM istek gövdesi üzerinden hesaplanan bir HMAC-SHA256.

Fiatside-Signaturehttp

Fiatside-Signature: t=<timestamp unix>,v1=<hex hmac-sha256>

Doğrulama, Node.jstypescript

import { createHmac, timingSafeEqual } from 'node:crypto'

// IMPORTANT : le corps doit etre le corps BRUT, avant tout parsing JSON.
// Re-serialiser l'objet change l'ordre des cles et invalide la signature.
export function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=') as [string, string]))
  const timestamp = Number(parts['t'])
  const signature = parts['v1']
  if (!timestamp || !signature) return false

  // Rejeu : une signature valide capturee hier ne doit pas etre rejouable aujourd'hui.
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false

  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')
  const a = Buffer.from(expected, 'hex')
  const b = Buffer.from(signature, 'hex')
  // Comparaison a temps constant : un === laisse fuiter la signature octet par octet.
  return a.length === b.length && timingSafeEqual(a, b)
}

Ayrıştırmadan önce ham gövdeyi imzalayın. JSON nesnesini yeniden serileştirmek anahtar sırasını ve boşlukları değiştirir: imza artık eşleşmez ve uzun süre ararsınız.
Sabit zamanda karşılaştırın. === karşılaştırması ilk farklı baytta durur ve bu da bir saldırganın beklenen imzayı bayt bayt ölçmesine olanak tanır.
Ötesini reddet 300-saniyelik tolerans penceresi. Bu kontrol olmadan, dün yakalanan geçerli bir istek bugün yeniden oynatılabilir kalır.
İşlemeden önce 200 yanıtı verin. Olayı kuyruğunuza koyun ve sonra işleyin: uzun işlem, olayı almış olsanız bile bir zaman aşımına ve dolayısıyla yeniden denemeye neden olur.

Yeniden denemeler ve sıralama

2xx olmayan herhangi bir durum veya hiç yanıt verilmemesi, aşağıdaki programa göre yeniden denemeyi tetikler.

Yeniden denemeler ve sıralama
Deneme	Gecikme
1	anında
2	30 s
3	2 min
4	10 min
5	1 h
6	6 h

Varış sırası garanti edilmez. Bir ödeme olayı, mantıksal olarak ondan önce gelen onay olayından önce gelebilir: alış sırasına değil, sipariş durumuna güvenin.
Aynı olay iki kez gelebilir. Olay kimliğini saklayın ve zaten işlenmiş bir kimliği yok sayın: alıcınızda idempotency sizin sorumluluğunuzdur ve bunu sağlamak kolaydır.
Kendi tarafınızda herhangi bir şeyi alacaklandırmak için yük içeriğindeki tutarlara asla güvenmeyin. Siparişi API üzerinden yeniden okuyun: yük bir şeyin olduğunu söyler, API tam olarak ne olduğunu söyler.
Son denemeden sonra olay düşer ve olay günlüğünüzde görünür kalır. Manuel olarak tekrar oynatabilirsiniz.