Skip to main content

12. Transaction Status Handling

This section explains how to interpret and handle transaction statuses returned by SADAD via Callback URL and Webhook notifications.

Correct status handling is critical to:

  • Prevent double order fulfilment
  • Avoid premature failure marking
  • Ensure accurate reconciliation and settlement

Official Transaction Status Values​

SADAD uses the following numeric status codes across callback and webhook:

CodeStatusMeaning
1In ProgressTransaction is created but not yet finalized
2FailedTransaction failed or was declined
3SuccessfulTransaction completed successfully
info

Status values are final only when transactionStatus = 2 or 3.
Status 1 must always be treated as temporary.

Where Status Is Received​

ChannelPurposeFormat
Callback URLFinal customer redirection resultForm POST (x-www-form-urlencoded)
WebhookReliable server-side notificationJSON POST

Merchants are strongly advised to support both.

🟡 Status = 1 (In Progress)​

This status indicates:

  • The payment flow has started
  • Bank or wallet authorization is pending
  • Final confirmation is awaited

Recommended handling:

  • Save the transaction as PENDING
  • Do not deliver goods/services
  • Do not retry payment automatically
caution

Never treat In Progress as a failure. Many transactions complete successfully later.

🔴 Status = 2 (Failed)​

This status indicates:

  • Payment was declined
  • Authentication failed
  • Bank rejected the transaction
  • Customer abandoned payment

Recommended handling:

  • Mark order as FAILED
  • Allow the customer to retry payment
  • Log failure reason for support review

🟢 Status = 3 (Successful)​

This status indicates:

  • Payment authorized and captured
  • Funds will be settled as per SADAD cycle

Recommended handling:

  • Mark order as PAID
  • Fulfil the order
  • Send confirmation to customer

End-of-Day Auto Reconciliation (Important)​

All transactions that remain In Progress (status = 1) are automatically re-evaluated after 12:00 AM (Qatar time) once final confirmation is received from the bank.

These transactions will be updated to either:

  • 2 → Failed, or
  • 3 → Successful
important

Merchants must re-check pending transactions after midnight
before assuming a permanent failure.

Why In-Progress Updates Occur​

This behaviour may occur due to:

  • Delayed bank responses
  • Wallet authentication delays
  • Temporary network issues
  • Customer closing the browser/app early

SADAD continuously reconciles such cases with issuing banks to ensure final accuracy.

Common Merchant Mistakes​

❌ Treating In Progress as failure
❌ Delivering goods before final success
❌ Ignoring webhook updates
❌ Not reconciling pending transactions

Best Practice Summary​

  • Always verify status server-side
  • Prefer webhook for reliability
  • Use callback for customer UX
  • Reconcile pending transactions daily
  • Never trust client-side status alone

If you need clarification on any transaction state, contact SADAD Support at
📧 [email protected]