İşletmeye giden ödeme callback'leri (outbound)

Ödemenin cüzdanı ve ağı için webhook tanımlıysa, ödeme servisi Apex'ten işletmenizin yapılandırdığı URL'lere POST ile JSON gönderir. Bu akış, Apex'e gelen webhook REST uçlarından (listele, oluştur, güncelle, sil) ayrıdır.

URL'ler

• host + success_path — mutlak URL olarak çözülür (host origin, success_path göreli veya mutlak yol birleşimi).
• host + error_path — hata callback'leri için aynı çözümleme.

Hangi yolun kullanılacağı callback type alanına göre belirlenir: başarı senaryoları success_path, hata senaryoları error_path üzerinden gider.

Kimlik doğrulama

auth_type basic ise kullanıcı adı/şifre tanımlıysa Basic auth gönderilir. token ise Bearer token gönderilir. Kimlik bilgisi yoksa istek kimliksiz gönderilir.

İstek gövdesi (sözleşme)

Tüm outbound ödeme webhook'ları aynı zarfı kullanır:

{
  "type": "payment_deposited",
  "payment": {
    "id": "…",
    "external_id": "…",
    "node_id": "…",
    "wallet_id": "…",
    "network_id": "…",
    "member_id": "…",
    "currency_id": "…",
    "deal_id": 0,
    "price": 0,
    "paid_price": 0,
    "payment_method": "web3",
    "payment_group": "product",
    "payment_address": "…",
    "status": "blockchain_deposited",
    "transaction_hash": "…",
    "metadata": "…",
    "completed_at": "2026-01-01T00:00:00Z",
    "diamond_address": "…",
    "created_at": "2026-01-01T00:00:00Z"
  }
}

• type (string): olayı tanımlar (aşağıdaki tablo). Teslimat loglama ve aynı type için retry akışında da bu değer kullanılır.
• payment: gönderim anındaki ödeme anlık görüntüsü (boş alanlar çıkarılabilir).

Content-Type: application/json.

type ve hedef URL

type	Hedef	Ne zaman
payment_deposited	success	Deal için zincirde yatırım algılandı; ödeme deposited durumuna geçti (cron).
payment_create_failed	error	create_payment custody/zincir tarafında hata.
payment_cancelled	success	cancel_payment custody tamamlandı.
payment_cancel_failed	error	cancel_payment custody hatası.
payment_refunded	success	refund_payment custody tamamlandı.
payment_refund_failed	error	refund_payment custody hatası.
payment_refund_init_failed	error	İade akışı custody öncesi başarısız (ör. refund consumer doğrulama/kurulum).

Create payment zincirde başarılı olduğunda (blockchain_created) işletmeye ayrı bir “başarı” webhook'u gönderilmez; yatırım algılandığında payment_deposited ile tek başarı bildirimi verilir (çift bildirim önlenir).

Retry

2xx dışı veya ağ hatasında teslimat, (webhook_id, payment_id, type) başına en fazla 5 deneme ile otomatik tekrarlanır. Başarılı bir payment_deposited, aynı ödeme için sonradan gelecek payment_cancelled / payment_refunded akışlarını engellemez.

Idempotency

Uç noktanız callback'leri en az bir kez alabilir; 2xx dönene kadar aynı type yeniden denenebilir. Yan etkileri payment.id + type (ve isteğe bağlı status / transaction_hash) ile tekilleştirin.