Yükler

Her webhook gövdesi sürümlenmiş bir zarftır. data nesnesi, ilgili durum API'sinin döndürdüğü satıcıya dönük kaynak sözleşmesiyle aynıdır; işleyiciniz kısmi deltaları birleştirmek yerine eksiksiz bir anlık görüntü uygulayabilir. Bu, üç kaynağın hepsi için geçerlidir: faturalar, çekimler ve kanal yatırmaları aynı zarfı ve aynı yük kuralını paylaşır.

Zarf

Alan	Tip	Sözleşme
event_id	string	Kararlı önekli kimlik (evt_…); X-Webhook-Id ile aynıdır ve yeniden denemeler ile tekrar gönderimlerde değişmez
event_type	string	Olay kataloğundaki değerlerden biri
version	integer	Yük şeması sürümü. Güncel sürüm 1
occurred_at	Unix saniye	Kaynak geçişinin zamanı; teslimat zaman damgasının aksine yeniden denemede değişmez
data	object	Bu olay için tam fatura, çekim veya kanal yatırması anlık görüntüsü

event_id bir teslimat kimliğidir: tek bir uç noktanın, tek bir geçişe ait kopyası. Aynı olaya abone iki uç nokta, aynı ödeme için iki farklı evt_ değeri alır. İş kimliği ise data içindeki kaynak kimliğidir — inv_…, wdr_… veya pcd_… — ve uç noktalar, geçişler ve tekrar gönderimler boyunca aynı kalır. Aynı ödemeyi iki kez saymamak için iş kimliğini, aynı teslimatı iki kez işlememek için event_id değerini kullanın.

Pahalı işe başlamadan önce event_id, event_type, version ve ham gövdeyi saklayın. Entegrasyonunuzun desteklemediği bir şema sürümünü, şeklini tahmin etmek yerine reddedin.

Fatura yükü

Örnek: invoice.paid.

{
  "event_id": "evt_J7EEYeL9pZJukfj2c5OQ44",
  "event_type": "invoice.paid",
  "version": 1,
  "occurred_at": 1739281200,
  "data": {
    "invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
    "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
    "status": "paid",
    "is_final": true,
    "is_test": false,
    "payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
    "order": {
      "external_id": "order-12345",
      "client_id": "customer-67890",
      "amount": "100.00",
      "currency": "USD"
    },
    "payment": {
      "currency": "USDT",
      "network": "TRC20",
      "chain_id": 728126428,
      "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "expected": "50.00",
      "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
      "exchange_rate": "2.00",
      "paid": "50.00",
      "remaining": "0",
      "fee": "0.50",
      "net": "49.50",
      "transfers": [
        {
          "tx_hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
          "amount": "50.00",
          "status": "confirmed",
          "created_at": 1739281020,
          "confirmed_at": 1739281200,
          "required_confirmations": 19,
          "estimated_confirmation_at": 1739281080,
          "explorer_url": "https://tronscan.org/#/transaction/abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        }
      ]
    },
    "expires_at": 1739284200,
    "completed_at": 1739281200,
    "created_at": 1739277600,
    "updated_at": 1739281200
  }
}

Fatura data alanı Fatura Getir yanıtını izler. Mevcut durum için henüz var olmayan alanlar JSON sözleşmesinde null veya eksiktir; durum otoritesi olarak status ve is_final kullanın.

Çekim yükü

Örnek: withdrawal.completed.

{
  "event_id": "evt_CbYeOgBp9Kt2U3j74fxxLl",
  "event_type": "withdrawal.completed",
  "version": 1,
  "occurred_at": 1739281200,
  "data": {
    "withdrawal_id": "wdr_7K2M9P4Q8R1X5Z3A0bC2dE",
    "external_order_id": "payout-12345",
    "status": "completed",
    "is_final": true,
    "is_test": false,
    "amount": "25.00",
    "fee": "0.50",
    "currency": "USDT",
    "network": "TRC20",
    "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    "tx_hash": "7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
    "explorer_url": "https://tronscan.org/#/transaction/7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
    "created_at": 1739277600,
    "completed_at": 1739281200
  }
}

Çekim data alanı Çekim Getir yanıtını izler. tx_hash ve explorer_url, izlenen bir zincir üstü işlem mevcut olduğunda doldurulur; status yerine geçmezler.

Kanal yatırması yükü

Örnek: payment_channel.deposit.confirmed.

{
  "event_id": "evt_J7EEYeL9pZJukfj2c5OQ44",
  "event_type": "payment_channel.deposit.confirmed",
  "version": 1,
  "occurred_at": 1767225930,
  "data": {
    "id": "pcd_8ScRvL4jNq2XkB7mTfZdWu",
    "payment_channel_id": "pc_2QhKZv6mRt9WdA3nYpLbXf",
    "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
    "payment_channel_external_id": "customer-42",
    "status": "confirmed",
    "is_final": true,
    "is_test": false,
    "currency": "USDT",
    "network": "TRC20",
    "chain_id": 728126428,
    "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "gross": "100",
    "fee": "1",
    "net": "99",
    "applied_fee_percent": 1.0,
    "customer_fee_percent": 0,
    "tx_hash": "9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25",
    "transfer_id": "9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25:41a614f803b6fd780986a42c78ec9c7f77e6ded13c:41c9f6a2b7d0138e54ca3b91f6072ed48a5c1e93b7:0",
    "source_address": "TW9s4RkAqBnLpVdX2ChYzUeGm7QfKt3NbZ",
    "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    "block_height": 68421905,
    "first_included_block_timestamp": 1767225900,
    "explorer_url": "https://tronscan.org/#/transaction/9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25",
    "created_at": 1767225870,
    "updated_at": 1767225930,
    "confirmed_at": 1767225930
  }
}

Yatırma data alanı Kanal Yatırması Getir yanıtını izler. Durum otoritesi status ve is_final'dır; applied_fee_percent ile customer_fee_percent, o yatırma için dondurulmuş oranlardır ve fiyatlandırmanızı değiştirdiğinizde oynamaz.

Üç yatırma olayı da aynı nesneyi taşır; bu yüzden confirming yükü bile kanalı, müşteri kimliğini, tutarı ve zincir üstü kanıtı verir. confirming ve reorged bilgi amaçlıdır ve sırasız gelebilir — hiçbiri, confirmed olduğunu bildiğiniz bir yatırmayı geri almasın.

Uyumluluk

• Ekleyici alanlar sürüm değişikliği olmadan görünebilir. İşleyicinizin kullanmadığı alanları yok sayın.
• Mevcut alan anlamları bir yük sürümü içinde değişmez.
• Kimlikleri ve ondalık tutarları dize olarak işleyin. Önekli kimlikleri UUID olarak veya parayı ikili kayan nokta olarak ayrıştırmayın.
• JSON'u ayrıştırmadan önce imzayı ham baytlara karşı doğrulayın. Nesneyi yeniden serileştirmek imzalanan girdiyi değiştirir.