Event Payload Reference

Payment notification payload fields and event types.

All webhook notifications are JSON payloads sent via HTTP POST. Your handler must parse JSON and return 200 OK quickly.

Common fields

Field	Description
`transactionId`	Gateway transaction UUID
`orderId`	Merchant order reference
`amount`	Transaction amount
`currencyCode`	ISO numeric or alpha currency
`status`	e.g. `Approved`, `Declined`
`type`	Event type (see below)
`cardScheme`	Card brand
`rrn`	Retrieval reference number

Important: Always store transactionId and orderId together for reconciliation and idempotent processing.

Event types

type	Description
`Sale`	Direct sale completed
`Capture`	Pre-auth captured
`CreditVoid`	Authorization voided
`Refund`	Refund processed

Example payloads

{
  "transactionId": "2232e99b-0257-47d5-bbfd-022c8951767f",
  "orderId": "PAY-1781872369616",
  "amount": 0.2,
  "currencyCode": "682",
  "status": "Approved",
  "type": "Sale",
  "cardScheme": "Mada",
  "channel": "Payment Gateway"
}

Approved sale: When type is Sale and status is Approved, you may fulfill the order after idempotency checks pass.

Declined payments: Do not fulfill orders when status is Declined. Cross-check with the status API if unsure.

Handler requirements

Your webhook endpoint must be reachable over HTTPS from DigetPay. Map incoming orderId values to internal orders, store transactionId for status and refund APIs, return 200 quickly before heavy processing (use a queue for fulfillment), and verify webhook signatures when a secret is configured.

See Webhook Security for signature verification and Receiving Webhooks for handler requirements.

Updated about 2 months ago

Did this page help you?