Step 6 - Handle the post-payment responses (notifications)
PayTabs provides you with the backend packages that make the integrating with PayTabs payment gateway very easy by providing ready-made classes that handle the payment process.
This article is dedicated to walking you through how to handle the payment response sent from PayTabs after the payment. Handling the response right will empower you to make sure to handle the user experience according to the payment status as well as and updating the order status in your database.
via The IPN response
The Instant Payment Notification (IPN) is the payment status notification to the configured URL, and it is a pure server-to-server connection (i.e: It is not a browser-based request).
As soon as a transaction is created or altered, IPN will instantly send a notification to the merchant’s specified IPN Listener URL, which can have any code that will assist in updating ERP or dependent systems. Alternatively, you may wish to save this information in your local database.
To get the best out of this, it's highly recommended to check our How to configure Instant Payment notification (IPN)? solution article.
What you need to do is to manage the IPN URL, and for that, you need to check our Step 3 - Manage the Return and Callback URLs solution article. The next main step would be to initiate a route to receive this [POST] response according to your business needs.
You should know that since the request is coming from an external system, the CSRF token needs to be excepted. You can either add your previous route to the VerifyCsrfToken middleware $except array Or by initiating this return route in the api.php route file, not the web.php one.
via The Callback URL response
The callback response is a server-to-server POST response that is sent (to a pre-defined HTTPS URL) with the full detailed transaction information once the payment process comes to an end (whether the customer cancels, pays, or fails to pay), as shown below. It doesn't depend on the customer's actions, and the response will be sent anyway.
{
"tran_ref": "TST223480140XXXX",
"merchant_id": 31000,
"profile_id": 81000,
"cart_id": "cart_11111",
"cart_description": "Description of the items/services",
"cart_currency": "SAR",
"cart_amount": "500.00",
"tran_currency": "SAR",
"tran_total": "500.00",
"tran_type": "Sale",
"tran_class": "ECom",
"customer_details": {
"name": "Technical Support Team",
"email": "[email protected]",
"phone": "+966 55 xxxxxx6",
"street1": "address street",
"city": "Jeddah",
"state": "Makkah",
"country": "SA",
"zip": "12345"
"ip": "156.221.244.35"
},
"shipping_details": {
"name": "Technical Support Team",
"email": "[email protected]",
"phone": "+966 55 xxxxxx6",
"street1": "address street",
"city": "Jeddah",
"state": "Makkah",
"country": "SA",
"zip": "12345"
"ip": "156.221.244.35"
},
"payment_result": {
"response_status": "D",
"response_code": "344",
"response_message": "Acquirer is unable to process this request",
"acquirer_message": "ERR_00:Technical Failure",
"cvv_result": " ",
"avs_result": " ",
"transaction_time": "2022-12-14T15:53:58Z"
},
"payment_info": {
"payment_method": "Visa",
"card_type": "Credit",
"card_scheme": "Visa",
"payment_description": "4111 11## #### 1111",
"expiryMonth": 12,
"expiryYear": 2022
},
"ipn_trace": "IPNS0004.6399F196.00000FD3"
}
Since it's a server-to-server call, the callback URL MUST be an available, accessible, and public URL
What you need to do is to manage the IPN URL, and for that, you need to check our Step 3 - Manage the Return and Callback URLs solution article. The next main step would be to initiate a route to receive this [POST] response according to your business needs.
You should know that since the request is coming from an external system, the CSRF token needs to be excepted. You can either add your previous route to the VerifyCsrfToken middleware $except array Or by initiating this return route in the api.php route file, not the web.php one.
Verify the IPN/Callback Response
It's highly recommended to verify the Return response first. Verifying the received object is a mandatory step to ensure that the request source is PayTabs itself. To know how to perform this, kindly check our How to verify the response received from PayTabs? (Signature Verification) solution article.