Skip to main content

Callback notification

Callback notification is the primary way to receive updates regarding the payment status, so you must implement that correctly in your application.
This service allows you to receive a notification in case of an event has occurred in the payment life cycle.


To use the callback and receive notifications, you must set up the notification_url.

  • You can set it up from the dashboard by clicking on your avatar icon in the right corner.

Delivery protocol

When the system send an event to your server , your system should replay with a status_code= 200.
If it's not successfully delivered, the system will make up to three additional attempts between each attempt, there will be an increased interval, and no further delivery attempts will be made if the callback is not successfully delivered. However, you can resend it manually from the dashboard, but you must update the notification_url as well.


Please note that due to the asynchronous nature of network requests, it is possible for a callback delivery confirmation (HTTP response with a 200 series status code) to not properly arrive from the callback's target server. Therefore it is possible in case of severe network faults for the target server to receive a callback, respond to it with a 200 series HTTP status code, and then receive the same callback after an interval.


We will send you a notification when some events/operations Occur in the payment life cycle.

you can choose what type of events to listen for by choosing them from the dasbhoard .

List of Events

Event nameDescription
saleIt's emitted when a purchase is executed. This happens as a result of POST /api/v1/session/ request executed successfully or any of the tokenization/recurring API methods, including scheduled payments.
3dsIt's emitted when the payment cycle enters the 3DS stage.
redirectIt's emitted when redirect_url is sent back as a result of the POST /api/v1/session/ or the recurring the api request.
refundIt's emitted when a refund transaction is performed.
voidIt's emitted when a void transaction is performed.
recurringIt's emitted when there is a scheduled payment occurs.
chargebackIt's emitted when the bank invokes a chargeback notification.

Transaction status

Along side with the event type you will receive the status of that event .


⚠️ Pay attention

A successful transaction does not mean a successful payment. For example, the payment is successful if the transaction has status = success and type = sale.
The payment is unsuccessful if the transaction has status = success and type = redirect.

List of Transaction status

Transaction statusOperation typeDescription
successsale,3ds,redirect,refund, void,recurring,chargebackThe transaction is completed successfully in the payment platform.
failsale, refund, void, recurringThe transaction has errors and is not validated by the payment platform.
waitingsale, refund,void, recurringThe transaction is being processed by the payment platform.

Callback parameters

The following is a list of all possible values in the callback notification.

idstringrequireduuidtransaction iddc66cdd8-d702-11ea-9a2f-0242c0a87002
order_numberstringrequiredorder idorder-1234
order_amountfloatrequiredorder amount2.00
order_currencystringrequiredISO 4217currency (3-character code)SAR
order_descriptionstringrequiredproduct descriptiona gift
typestringrequiredoperation type : [sale,3ds,redirect,refund,void,chargeback]sale
statusstringrequiredtransaction status : [success, fail, waiting]success
reasonstringoptionalDecline or error reason (for "sale" and "refund" operation types only). It displays only if the transaction has a FAIL statusThe operation was rejected. Please contact the site support
rrnstringoptionalISO 8583Retrieval Reference Number value from the acquirer system2334343434
approval_codestringoptionalApproval code value from the acquirer system000
cardstringoptionalmaskedcard number masked41111*1111
card_expiration_datestringoptionalcard expiration date12/2022
card_tokenstringoptionalCard token. It is available if the parameter req_token was enabledVjFRaUxDSmhiR2NpT2lKU1V6STFO
customer_namestringoptionalcustomer's first and last nameKhalid nasser
customer_emailstringoptionalemailcustomer's email
customer_countrystringoptionalISO 3166-1 alpha-2customer's countrySA
customer_statestringoptionalcustomer's stateNajd
customer_citystringoptionalcustomer's cityRiyadh
customer_addressstringoptionalcustomer's address123 sample street
customer_ipstringrequiredipv4customer's ip10.10.10.10
datedateoptionaltransaction date2020-08-05
recurring_inti_trans_idstringoptionaluuidReference to the first transaction that initializes the recurring (provided if recurring was initialized)dc66cdd8-d702-11ea-9a2f-0242c0a87099
schedule_idstringoptionalIt is available if schedule is used for recurring sale
hashstringrequiredA special signature is used to validate callback Addition in the Signature sectionMust be SHA1 of MD5 encoded string (uppercased): payment_public_id + order.number + order.amount + order.currency + order.description + merchant.pass

Sample callback notification request

order_description= gift
date=2022-07-05 09:22:09
customer_name=Khalid Nasser
customer_address=exit 10

Update the notification_url

  • If you want to add a new one or update the existing URL from the dashboard, replace the old one and save it.