Skip to main content

14. Error Handling & Failure Reasons

This section explains how payment failures and errors are communicated by SADAD during Web Checkout 2.1 transactions.

SADAD does not expose a fixed or standardized error-code catalog for all failure scenarios. Instead, merchants should rely on:

  • transaction_status
  • RESPCODE
  • RESPMSG
  • Context of where the failure occurred

This approach aligns with issuer-side payment processing realities and international payment scheme practices.

Where Failures Can Originate​

Payment failures can originate from multiple sources:

SourceDescription
Merchant systemInvalid or incomplete request data
CustomerPayment cancellation or timeout
Issuing bankDeclines based on risk, balance, or rules
Wallet providerAuthentication or authorization failure
NetworkTemporary connectivity or processing delays

Key Fields to Inspect​

When a transaction fails, merchants should primarily inspect:

FieldDescription
transaction_statusFinal state of the transaction (1, 2, 3)
RESPCODEHigh-level response indicator
RESPMSGHuman-readable failure or status message
STATUSTextual transaction state
transaction_numberSADAD transaction reference
important

Only transaction_status = 2 represents a final failure. Status 1 (In Progress) is temporary.

Common Failure Message Patterns​

The following messages are examples of typical issuer or system responses. Exact wording may vary depending on the bank, wallet, or payment method.

Issuer / Bank Declines​

Typical MessageMeaningRecommended Merchant Action
Transaction declinedIssuing bank rejected the transactionAsk customer to contact their bank
Insufficient fundsNot enough balance availableRetry with another payment method
Card not permittedCard not enabled for online useCustomer to enable card or retry
Risk / security rejectionBank fraud or risk rules triggeredCustomer to verify with bank

Customer-Driven Failures​

Typical MessageMeaningRecommended Merchant Action
Payment cancelledCustomer cancelled checkoutAllow safe retry
Authentication failedOTP / wallet authentication failedAsk customer to retry
Authentication timeoutCustomer did not complete verificationRetry payment

Merchant / Request Errors​

Typical MessageMeaningRecommended Merchant Action
Invalid requestMissing or invalid parametersValidate request payload
Invalid signatureSignature mismatchRecheck signature logic
Invalid merchantMerchant ID or key mismatchConfirm MID & environment

System / Network Conditions​

Typical MessageMeaningRecommended Merchant Action
System errorTemporary processing issueRetry after some time
Gateway timeoutBank or network delayRetry later
Service unavailableTemporary outageMonitor & retry

In-Progress Transactions & Delayed Updates​

Some transactions may remain In Progress (transaction_status = 1) initially.

This may occur due to:

  • Delayed bank responses
  • Wallet authorization delays
  • Temporary network interruptions
  • Customer closing the browser/app early

Such transactions are automatically reconciled after 12:00 AM (Qatar time) and updated to either Success (3) or Failure (2) based on final bank confirmation.

Best Practices for Handling Failures​

  • Do not rely on error text alone
  • Always use transaction_status as the source of truth
  • Never expose raw technical messages directly to customers
  • Log full callback and webhook payloads server-side
  • Use webhooks to capture delayed updates
  • Allow customers to retry failed transactions safely

Common Merchant Mistakes​

❌ Assuming all failures are final immediately
❌ Treating In Progress as failure
❌ Ignoring webhook updates
❌ Hard-coding error messages or logic

Important Disclaimer​

caution

Exact failure messages are returned by banks, wallets, or payment networks and may vary by issuer and payment method.

SADAD does not control or override issuer-side decline decisions.

If failure behavior appears inconsistent or unclear, contact SADAD Support with:

  • Merchant ID
  • Order ID
  • Transaction number

📧 [email protected]