Payment Status Guidelines

How each invoice status should update your orders, and what to tell your customer.

This page explains how a SADAD Pay invoice moves through its statuses, and how to reflect each one in your own order system and in what you tell your customer. To learn how to read the status from the API, see Verify Payment Status.

The invoice lifecycle

Unpaid
Created and waiting. Failed attempts keep it here.
Paid
The customer paid. Complete the order.
Deposited
SADAD Pay transferred the money to your bank.
Refunded
After a full refund. A partial refund keeps the invoice Paid or Deposited.
Canceled
Stopped before payment. Can no longer be paid.

Unpaid → Paid → Deposited is the normal path. A full refund moves it to Refunded; a partial refund only raises refunded_Amount. Canceled and Expired can only follow Unpaid. Expired appears once the payment page is opened after the expiry date.

FromToWhat causes it
—UnpaidYou create the invoice (portal, API, payment link or embedded session)
UnpaidPaidThe customer pays successfully
UnpaidCanceledYou cancel it in the portal, or with DELETE /api/Invoice/delete
PaidDepositedSADAD Pay settles the money to your bank account
Paid or DepositedRefunded (full refund) or no change (partial refund)You refund the payment. After a full refund the status becomes Refunded. After a partial refund it stays the same and refunded_Amount goes up. See Refunds.

🚧

Expired invoices can still say Unpaid

When an invoice passes its expiry_Date, the customer sees Expired on the payment page and can no longer pay, The API changes the status to Expired only after someone opens the payment page. Until then it keeps returning "status": "Unpaid". To know whether an unpaid invoice can still be paid, compare expiry_Date with the current date.

1254

Invoice statuses as they appear in the portal: Paid, Unpaid, Refunded and Cancelled

Map SADAD Pay statuses to your orders

Use this as a starting point for your order statuses:

SADAD Pay invoiceYour orderShow the customer
Unpaid, no attempts yetPending paymentThe payment link or button
Unpaid, last attempt FailedPending payment"Your payment was not completed. No money was taken. Please try again." and a retry button
Unpaid, last attempt PendingPending payment"We're waiting for your payment to be confirmed." Check again in a few minutes.
Expired, or Unpaid past expiry_DateExpired or Cancelled"This payment link has expired." Create a new invoice if they still want to buy.
PaidPaid, then Processing"Thank you, your payment was received." and the order confirmation
DepositedPaid (no change for the customer)Nothing new
Refunded, or Paid/Deposited with refunded_Amount above 0Refunded (or Partly refunded)"Your refund has been processed."
CanceledCancelled"This order was cancelled."

📘

Attempts are in transactions

"Last attempt" means the last entry in the invoice's transactions array. Its status is Pending, Failed or Success. See Payment attempts.

What to show on your return pages

SADAD Pay sends the customer back to your Success URL or Fail URL with invoice_id added. Verify the invoice first, then show the page that matches the verified status, not the URL they arrived on.

Verified resultPage to show
Paid and the checks passOrder confirmation
Unpaid with a Failed attemptPayment failed, with a button to try again
Unpaid with a Pending attempt, or the API cannot be reached"Payment is being confirmed", and check again shortly
Amount or order number does not match"We could not confirm your payment." Hold the order and review it

👍

Let the customer retry with the same invoice

An unpaid invoice can be paid again until it expires. Send the customer back to the same payment link rather than creating a new invoice. This avoids two invoices for one order.

Special cases

The customer paid two invoices for one order

This can happen if you create a new invoice on every retry. Complete the order once, using the first Paid invoice, and refund the other. Searching by your order number with getallbypage and Ref_Number shows every invoice for that order.

The invoice was paid after you cancelled the order

For example, the customer paid just before you marked the order as expired. If you can still fulfil it, reopen the order. If not, refund the payment. To avoid this, cancel the invoice too (DELETE /api/Invoice/delete) when you cancel an unpaid order.

The amount does not match

Never complete an order whose verified amount is different from the order total. Hold it and contact [email protected] with the invoice ID.

A paid order is refunded later

A refund can happen after the order is complete, for example when you refund from the portal. Check refunded_Amount to see how much was returned, and update the order. After a full refund the invoice status is Refunded; after a partial refund it stays Paid or Deposited.

Good practice

  • Save the invoice ID against your order as soon as you create the invoice.
  • Always verify on your server before changing an order. See Verify Payment Status.
  • Make updates safe to repeat. The return page, a webhook and your scheduled check can all report the same payment.
  • Never mark an order as failed just because the customer returned to your Fail URL, closed the page, or the API could not be reached. Keep it pending and check again.
  • Check expiry yourself, using expiry_Date.
  • Keep transactionID for paid invoices. You will need it for support and refunds.

Next steps