10. Callback URL & Response Parameters

After a customer completes (or exits) the SADAD Web Checkout flow, SADAD sends the transaction result to the merchant via an HTTP POST request to the configured CALLBACK_URL.

The callback is primarily used to:

• Display the payment result to the customer
• Update order status on the merchant system

Merchants are strongly advised to also implement Webhook handling for reliable server-to-server transaction updates.

---

Callback Trigger Conditions

The callback is triggered when:

• The customer completes the checkout flow, or
• The customer exits the payment page after authentication

The callback depends on the customer’s browser or app and should not be treated as the only source of truth.

📘 For reliable updates, see:
→ Webhook Integration

---

Callback Request Format

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Encoding: URL-encoded key–value pairs

The callback payload is not JSON.

---

Important Callback Parameters

Parameter	Example Value	Description
MID	7015085	SADAD Merchant ID
ORDERID	ORD-20251216-001	Original merchant order ID
RESPCODE	3	Transaction response code
RESPMSG	Txn Success	Human-readable message
TXNAMOUNT	150.00	Transaction amount
STATUS	TXN_SUCCESS	Overall transaction state
transaction_number	SD2883696582255	SADAD transaction reference
transaction_status	3	Final transaction status
website_ref_no	ORD-20251216-001	Merchant order reference
issandboxmode	1	Indicates sandbox (1) or live (0)
checksumhash	A1B2C3...	Signature for verification

---

Transaction Status Values

The transaction_status field indicates the current transaction state:

Value	Meaning
1	In Progress
2	Failed
3	Successful

Important Behaviour Note

note

Transactions marked as In Progress may be updated to Success or Failed automatically after 12:00 AM, following final confirmation from the issuing bank.

This behaviour typically occurs due to:

• Delayed bank or network responses
• Temporary connectivity issues
• Customer exiting the payment flow early

SADAD continuously reconciles such transactions and updates the final status once confirmation is received.

---

Sample Callback Payload

Below is an example of a callback payload posted to the merchant’s CALLBACK_URL:

MID=7015085
&ORDERID=ORD-20251216-001
&RESPCODE=3
&RESPMSG=Txn+Success
&STATUS=TXN_SUCCESS
&TXNAMOUNT=150.00
&issandboxmode=1
&transaction_number=SD2883696582255
&transaction_status=3
&website_ref_no=ORD-20251216-001
&checksumhash=4532c38dcbeac04f1e58766428116728a03d1ae28c566fc3abbcad687821b819

---

Verifying Callback Authenticity

Each callback includes a checksumhash to verify that the response was sent by SADAD.

To verify the callback:

1. Store the received checksumhash separately
2. Remove checksumhash from the received parameters
3. Sort the remaining parameters alphabetically by key name
4. Create a string starting with your Secret Key
5. Append the values of the sorted parameters
6. Generate a SHA256 hash
7. Compare the generated hash with the received checksumhash

If both values match, the callback is authentic.

note

The verification logic is identical to the request signature generation process, applied to the incoming callback payload.

For detailed hashing logic and language samples, refer to:
→ Signature Generation

---

How Merchants Should Handle Callbacks

Recommended handling approach:

• Always verify checksumhash before updating order status
• Treat transaction_status = 3 as final success
• Treat transaction_status = 2 as final failure
• Treat transaction_status = 1 as temporary
• Use webhooks to reconcile delayed or missed updates

---

Common Mistakes to Avoid

caution

• Updating order status without signature verification
• Treating callback as the only transaction update mechanism
• Assuming In Progress status is final
• Ignoring post-midnight status updates

---

What’s Next?

After handling the callback, ensure that:

👉 Webhook Processing is implemented
👉 Status Handling logic is in place

---

Need Help?

If you face issues with callback handling, contact:

📧 Contact SADAD Support

Please include:

• Merchant ID
• Order ID
• Callback timestamp
• Environment (Test or Live)