Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages. 



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.


 

In this article, we will walk you through the following:


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 with the full detailed transaction information response, 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 Callback URL, and for that, you need to check our Request/Response - The Callback URL solution article. The next main step would be to receive this [POST] response and handle it according to your business needs. Response_status and response_message can be much helpful in knowing exactly what is the transaction status. Also, you can check our Response_code and Response_status  solution article for more details.


You should know that since the request is coming from an external system, the CSRF token needs to be excepted.


via The Callback URL Response


The callback response, which is a one-time IPN, 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.


Since it's a server-to-server call, the callback URL MIUST be an available, accessible, and public URL



What you need to do is to manage the Callback URL, and for that, you need to check our Request/Response - The Callback URL solution article. The next main step would be to receive this [POST] response and handle it according to your business needs. Response_status and response_message can be much helpful in knowing exactly what is the transaction status. Also, you can check our Response_code and Response_status solution article for more details.


You should know that since the request is coming from an external system, the CSRF token needs to be excepted.


Response Payload Specifications


Parameter 

Sample Response

Nullable

Purpose 

tran_ref

TST2234701408580

❌

Indicates the Transaction Reference on the Paytabs side

check details on [Response Parameters | tran_ref]

cart_currency

USD

❌

Indicates the currency that used in creating the payment request

check details on [Response Parameters | cart_currency]

cart_amount

500.00

❌

Indicates the amounts that used in creating the payment request

check details on [Response Parameters | cart_amount]

tran_currency

USD

❌

Indicates the transaction currency as it had been stored on the Paytabs side, the acquirer, and the issuer

check details on [Response Parameters | tran_currency]

tran_total

500.00

❌

Indicates the amounts that have been deducted from the customer/cardholder.

check details on [Response Parameters | tran_total]

payment_result

   

 "payment_result": {
        "response_status": "A",
        "response_code": "G49776",
        "response_message": "Authorised",
        "transaction_time": "2022-12-13T16:42:56Z"
    }
JavaScript

❌

Indicates the Transaction results details, including the status, the code, the message, and the transaction time

check details on [Response Parameters | payment_result]

payment_info

   "payment_info": {
        "payment_method": "Visa",
        "card_type": "Credit",
        "card_scheme": "Visa",
        "payment_description": "4111 11## #### 1111",
        "expiryMonth": 12,
        "expiryYear": 2022
    }
JavaScript

❌

Indicates the form of payment information in detail. 
  
check details on [Response Parameters | payment_info]

token

JfN1DVw6w7hrM7mm1P11jNMbzFFAe9WU

✔

Only if the card has been tokenized (have a token created representing this card) the card token would be returned within the response. 
  
check details on [Response Parameters | token]

serviceId

8

❌

A parameter that is used internally by PayTabs technicals. 
  
check details on [Response Parameters | serviceId]

profileId

81784

❌

Indicates the profile that created the transaction. 
  
check details on [Request Parameters | profileId]

merchantId

31237

❌

Indicates the profile that created the transaction. 
  
check details on [Response Parameters | merchantId]

ipn_trace

PMNT0404.6398AB90.000109ED

❌

Indicates the code that PayTabs can trace this response with. 
  
check details on [Response Parameters | trace]



Sample Response Payload


{
        "tran_ref": "TST2234801409691",
        "merchant_id": 31237,
        "profile_id": 81784,
        "cart_id": "cart_11111",
        "cart_description": "Description of the items/services",
        "cart_currency": "EGP",
        "cart_amount": "500.00",
        "tran_currency": "EGP",
        "tran_total": "500.00",
        "tran_type": "Sale",
        "tran_class": "ECom",
        "customer_details":
         {
                "name": "Mohammed EL Rayes",
                "email": "[email protected]",
                "phone": "01008606003",
                "street1": "AAA, A, BBB",
                "city": "CCC",
                "state": "C",
                "country": "EG",
                "zip": "42121",
                "ip": "156.221.244.35"
        },
         "shipping_details": 
        {
                "name": "Mohammed EL Rayes",
                "email": "[email protected]",
                "phone": "01008606003",
                "street1": "AAA, A, BBB",
                "city": "CCC",
                 "state": "C",
                 "country": "EG",
                "zip": "42121"
          },
        "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"
}
JavaScript


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.







⌂ To get familiar with the whole process and the other steps, kindly navigate to our "The PT2 API Endpoints Integration Manual" solution article. 



    ⇦ And to get familiar with the rest of the steps regarding the previuos step "Step 5 - Handle the payment response" kindly click here.



    ⇨ And to navigate to the next step in the integration process "Step 7 - Manage Transactions" kindly click here.