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.

Usage

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.

note

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.

Events

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 name	Description
sale	It'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.
3ds	It's emitted when the payment cycle enters the 3DS stage.
redirect	It's emitted when redirect_url is sent back as a result of the POST /api/v1/session/ or the recurring the api request.
refund	It's emitted when a refund transaction is performed.
void	It's emitted when a void transaction is performed.
recurring	It's emitted when there is a scheduled payment occurs.
chargeback	It'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 .

note

⚠️ 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 status	Operation type	Description
success	sale,3ds,redirect,refund, void,recurring,chargeback	The transaction is completed successfully in the payment platform.
fail	sale, refund, void, recurring	The transaction has errors and is not validated by the payment platform.
waiting	sale, refund,void, recurring	The transaction is being processed by the payment platform.

Callback parameters

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

Parameter	Type	Mandatory	Format	Description	example
id	string	required	uuid	transaction id	dc66cdd8-d702-11ea-9a2f-0242c0a87002
order_number	string	required		order id	order-1234
order_amount	float	required		order amount	2.00
order_currency	string	required	ISO 4217	currency (3-character code)	SAR
order_description	string	required		product description	a gift
type	string	required		operation type : [sale,3ds,redirect,refund,void,chargeback]	sale
status	string	required		transaction status : [success, fail, waiting]	success
reason	string	optional		Decline or error reason (for "sale" and "refund" operation types only). It displays only if the transaction has a FAIL status	The operation was rejected. Please contact the site support
rrn	string	optional	ISO 8583	Retrieval Reference Number value from the acquirer system	2334343434
approval_code	string	optional		Approval code value from the acquirer system	000
card	string	optional	masked	card number masked	41111*1111
card_expiration_date	string	optional		card expiration date	12/2022
card_token	string	optional		Card token. It is available if the parameter req_token was enabled	VjFRaUxDSmhiR2NpT2lKU1V6STFO
customer_name	string	optional		customer's first and last name	Khalid nasser
customer_email	string	optional	email	customer's email address	test@test.com
customer_country	string	optional	ISO 3166-1 alpha-2	customer's country	SA
customer_state	string	optional		customer's state	Najd
customer_city	string	optional		customer's city	Riyadh
customer_address	string	optional		customer's address	123 sample street
customer_ip	string	required	ipv4	customer's ip	10.10.10.10
date	date	optional		transaction date	2020-08-05
recurring_inti_trans_id	string	optional	uuid	Reference to the first transaction that initializes the recurring (provided if recurring was initialized)	dc66cdd8-d702-11ea-9a2f-0242c0a87099
schedule_id	string	optional		It is available if schedule is used for recurring sale
hash	string	required		A special signature is used to validate callback Addition in the Signature section	Must be SHA1 of MD5 encoded string (uppercased): payment_public_id + order.number + order.amount + order.currency + order.description + merchant.pass

Sample callback notification request

  id=f0a51dfa-fc43-11ec-8128-0242ac120004
  order_number=order-1234
  order_amount=3.01
  order_currency=SAR
  order_description= gift
  type=sale
  status=success
  card=411111****1111
  card_expiration_date=12/2022
  schedule_id=4e46866c-f84b-11ec-8b4c-0242ac120007
  recurring_init_trans_id=f0a51dfa-fc43-11ec-8128-0242ac120004
  recurring_token=f0e24964-fc43-11ec-a7e0-0242ac120004
  date=2022-07-05 09:22:09
  hash=6d8d440e25bdfc5288616ce567496948d2562852
  customer_name=Khalid Nasser
  customer_email=success@gmail.com
  customer_country=SA
  customer_state=Najd
  customer_city=Riyadh
  customer_address=exit 10
  customer_ip=10.10.10.2

---

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.