Webhook Events

Pientegra webhook event type'ları, payload shape'leri ve önerilen business action'lar.

Tüm webhook'lar ortak bir envelope taşır:

{
  "eventId": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
  "eventType": "intent.approved",
  "occurredAt": "2026-04-28T13:15:00.000Z",
  "intent": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "D-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "100000",
    "currency": "TRY",
    "status": "APPROVED"
  }
}

Field	Açıklama
`eventId`	Delivery/event identifier. Retry attempt'leri arasında stable kalır; log ve duplicate detection için saklayın.
`eventType`	Stable event type. Business branching burada yapılır.
`occurredAt`	Business transition'ın Pientegra tarafında kaydedildiği an (UTC ISO 8601). Retry'lar arasında değişmez.
`intent`	Deposit event'lerinde bulunur.
`withdrawal`	Withdrawal event'lerinde bulunur.

Deposit events

`intent.created`

Deposit intent oluşturuldu. Çoğu entegrasyonda balance mutation gerekmez; bu event synchronous create response'un asenkron görünürlüğüdür.

{
  "eventType": "intent.created",
  "intent": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "D-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "100000",
    "currency": "TRY",
    "status": "RESERVED"
  }
}

Önerilen aksiyon: log/support görünürlüğü; kullanıcı bakiyesi güncellenmez.

`intent.approved`

Deposit onaylandı. Kullanıcı bakiyesi bu event ile credit edilmelidir.

{
  "eventType": "intent.approved",
  "intent": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "D-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "100000",
    "currency": "TRY",
    "status": "APPROVED"
  }
}

Önerilen idempotency key: intent.approved:<intent.id>.

`intent.rejected`

Deposit reddedildi. Kullanıcı bakiyesi daha önce credit edilmemiş olmalıdır.

{
  "eventType": "intent.rejected",
  "intent": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "D-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "100000",
    "currency": "TRY",
    "status": "REJECTED",
    "rejectedReason": "Tutar uyuşmazlığı"
  }
}

Önerilen aksiyon: pending UI/support state kapatılır.

`intent.auto_cancelled`

Kullanıcı ödeme yapmadı ve deposit URL expired oldu.

{
  "eventType": "intent.auto_cancelled",
  "intent": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "D-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "100000",
    "currency": "TRY",
    "status": "AUTO_CANCELLED"
  }
}

Önerilen aksiyon: pending UI/support state kapatılır.

Withdrawal events

`withdrawal.created`

Withdrawal kaydı oluşturuldu. Synchronous create response ile aynı operasyonun asenkron görünürlüğüdür.

{
  "eventType": "withdrawal.created",
  "withdrawal": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "W-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "250000",
    "currency": "TRY",
    "status": "PENDING_REVIEW"
  }
}

Önerilen aksiyon: log/support görünürlüğü. Balance modelinize göre pre-reserve daha önce yapılmış olabilir.

`withdrawal.sent`

Para gönderildi. Withdrawal için successful final state budur.

{
  "eventType": "withdrawal.sent",
  "withdrawal": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "W-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "250000",
    "currency": "TRY",
    "status": "SENT"
  }
}

Önerilen idempotency key: withdrawal.sent:<withdrawal.id>.

`withdrawal.rejected`

Pientegra request'i reddetti. Pre-reserve modelinde kullanıcı bakiyesi release veya refund edilmelidir.

{
  "eventType": "withdrawal.rejected",
  "withdrawal": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "W-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "250000",
    "currency": "TRY",
    "status": "REJECTED",
    "rejectedReason": "IBAN doğrulanamadı"
  }
}

Önerilen idempotency key: withdrawal.rejected:<withdrawal.id>.

`withdrawal.returned`

Para gönderildi ancak banka tarafından iade edildi. Pre-reserve modelinde kullanıcı bakiyesi geri yüklenmelidir.

{
  "eventType": "withdrawal.returned",
  "withdrawal": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "W-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "250000",
    "currency": "TRY",
    "status": "RETURNED",
    "returnedReason": "Hedef hesap kapalı"
  }
}

Önerilen idempotency key: withdrawal.returned:<withdrawal.id>.

Action summary

Event	Balance action
`intent.created`	No-op
`intent.approved`	Credit user balance (`amount`, ki bu `requestedAmount`'tan farklı olabilir)
`intent.rejected`	No credit; close pending state
`intent.auto_cancelled`	No credit; close pending state
`withdrawal.created`	Depends on your reserve model
`withdrawal.sent`	Finalize debit
`withdrawal.rejected`	Release/refund reserved balance
`withdrawal.returned`	Refund balance

Consumer skeleton

Idempotent consumer

async function handlePientegraEvent(event: PientegraWebhookEvent) {
  switch (event.eventType) {
    case 'intent.approved':
      await ledger.creditOnce({
        key: `intent.approved:${event.intent.id}`,
        userId: event.intent.externalUserId,
        amount: event.intent.amount,
      });
      return;

    case 'withdrawal.sent':
      await ledger.debitOnce({
        key: `withdrawal.sent:${event.withdrawal.id}`,
        userId: event.withdrawal.externalUserId,
        amount: event.withdrawal.amount,
      });
      return;

    case 'withdrawal.rejected':
    case 'withdrawal.returned':
      await ledger.refundOnce({
        key: `${event.eventType}:${event.withdrawal.id}`,
        userId: event.withdrawal.externalUserId,
        amount: event.withdrawal.amount,
      });
      return;

    default:
      await audit.log(event);
  }
}

Webhook Events

On this page