Guides
  1. Webhooks

Event Payload Reference

Payment notification payload fields and event types.

📘

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

Common fields

FieldDescriptionExample
transactionIdGateway transaction UUID2232e99b-0257-47d5-bbfd-022c8951767f
orderIdMerchant order referencePAY-1781872369616
amountTransaction amount0.2
currencyCodeTransaction currency using an ISO 4217 currency code682
statusCurrent transaction statusApproved
typeWebhook event typeSale
cardSchemeCard scheme/brand used for the transactionMada
channelTransaction channelPayment Gateway
rrnRetrieval Reference Number returned for the transaction when available609211307265
declineReasonReason associated with a declined transaction, when availableInsufficient funds
🚧

Important: Not every field is present in every event. Fields such as rrn and declineReason may only be included when they are applicable to the transaction or event.

🚧

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

Event types

The type field identifies the operation that generated the webhook notification.

TypeDescription
SaleSale/payment transaction
CaptureCapture of a previously authorized transaction
CreditVoidVoid of an authorization
RefundRefund transaction

Status values

The status field represents the current result of the transaction or event.

StatusDescription
ApprovedThe transaction or requested operation was successfully approved
DeclinedThe transaction or requested operation was declined
📘

Use the transaction status returned by DigetPay when determining whether an order should be fulfilled. Do not treat the webhook event type alone as proof of a successful payment.

Currency codes

currencyCode follows the ISO 4217 currency-code standard.

For example:

Numeric CodeAlpha CodeCurrency
682SARSaudi Riyal

For transactions processed in Saudi Riyal, DigetPay webhook payloads use:

{
  "currencyCode": "682"
}
📘

682 is the ISO 4217 numeric code for Saudi Riyal (SAR). Use the numeric currency code returned in the webhook when reconciling transaction data.

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",
  "rrn": "609211307265"
}

Processing events

Your webhook handler should use both type and status when determining what action to take.

For example:

  • Sale + Approved → payment was approved and can be considered for fulfillment after idempotency checks.
  • Sale + Declined → payment was not approved; do not fulfill the order.
  • Capture + Approved → the previously authorized amount was captured successfully.
  • Refund + Approved → the refund operation was approved.
  • CreditVoid + Approved → the authorization was successfully voided.

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

❗️

Declined payments: Do not fulfill orders when status is Declined. Cross-check the transaction status using the status API if the webhook result is unclear.

Idempotent processing

Webhook notifications may be delivered more than once. Your handler must be able to process duplicate notifications without creating duplicate business actions.

Use the transaction identifiers to maintain an idempotency record.

A recommended key is:

transactionId + type

Always retain the associated orderId for reconciliation and merchant-side order mapping.

Handler requirements

Your webhook endpoint must:

  1. Be reachable over HTTPS from DigetPay.
  2. Parse the incoming JSON payload.
  3. Verify the webhook signature when signature verification is configured.
  4. Use transactionId and orderId to identify the transaction and merchant order.
  5. Handle duplicate events idempotently.
  6. Return 200 OK quickly after accepting a valid event.
  7. Process heavy business operations asynchronously where possible.
  8. Use the status API when additional confirmation is required.
📘

See Webhook Security for signature verification and Receiving Webhooks for complete handler implementation guidance.

Field handling notes

transactionId

Use the gateway transaction ID to identify the DigetPay transaction when querying transaction status or performing supported follow-up operations.

orderId

Use the merchant order reference to map the webhook notification to the corresponding order in your system.

rrn

The Retrieval Reference Number may be returned for applicable card transactions. Store it when present if it is required for reconciliation or transaction investigation.

declineReason

declineReason provides additional information for a declined transaction when available. Do not assume that every declined transaction will contain this field.

currencyCode

The currency code identifies the currency used for the transaction. DigetPay currently documents 682 as the numeric ISO 4217 code for SAR.

channel

The channel field identifies the DigetPay channel through which the transaction was processed, such as Payment Gateway.

⚠️

Do not hard-code assumptions about optional fields. Your webhook parser should safely handle fields that are absent from a particular event payload.

Related guides

Updated 22 days ago

Did this page help you?