Handle Webhooks

DigetPay sends HTTP POST notifications to your configured webhook URL when payment events occur.

Webhooks are the most reliable way to confirm payments. Implement them before going to production.

Sequence diagram

sequenceDiagram
    autonumber
    participant Gateway as Payment Gateway
    participant DigetPay as DigetPay
    participant Merchant as Your Server

    Gateway->>DigetPay: Payment event (sale, capture, refund)
    DigetPay->>DigetPay: Update transaction record
    DigetPay->>Merchant: POST {merchantCallbackUrl}<br/>JSON payload
    Merchant-->>DigetPay: 200 OK
    Note over Merchant: Idempotent processing — same event may retry

Requirements

Requirement	Detail
HTTPS	Public TLS endpoint required
Response	Return `200` quickly (process async if needed)
Idempotency	Handle duplicate deliveries by `transactionId` / `orderId`

Critical: Return 200 OK within a few seconds. Slow handlers cause retries and duplicate processing.

Important: DigetPay may deliver the same event more than once. Always deduplicate by transactionId + type.

Example incoming payload

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

Store transactionId: This is the gateway transaction UUID — use it for status and refund APIs.

Expected response from your server

{
  "status": 200,
  "body": "OK"
}

Your endpoint should return HTTP 200 with a short body. Process fulfillment asynchronously after responding.

S2S callback ingress

For S2S integrations, the gateway may also post to:

{
  "method": "POST",
  "path": "/v1/payment/s2s/callback/{merchantId}",
  "note": "DigetPay validates and forwards to your merchant callback URL"
}

Configure your merchant callback URL during onboarding or via the Merchant Portal.

Next steps

Webhook Events — payload fields and event types
Webhook Security — signature verification
Webhook Configuration — manage URLs