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 the clarification of the return URL parameter. The return URL is the URL that PayTabs will redirect the customer to after he finishes the payment process (whether it's authenticated or not). 


The redirection to the return page comes with the transaction brief, and It depends on the customer's behavior, which means if the customer closes the browser right after the payment without waiting to be redirected back to your system, you will not receive this response. For more information please check our What is the Return URL vs. the Callback URL? solution article.


In this article, you will be going to know:


Specifications 


The Parameter Tag/Namereturn
JSON Example
{
     "return": "https://example.com/order/10001"
}

Data TypeString
Required
❌
Validation Rules
  • Valid URL
  • Recommended to pass it as an HTTPS URL, otherwise, will reflect on the response behavior.
Max Length255 Character 



Usage Workflow


Along with the required parameters mentioned in our Step 3 - PT2 API Endpoints | Initiating the payment solution article, you will need to set the "return" as shown below:


You can notice that the passed "return" parameter is already included within the response object.



Sample Request Payload

{
    "profile_id": "987654",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "USD",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",

    "return": "https://example.com/order/10001"
}


Sample Response Payload

{
    "tran_ref": "TST2231101374414",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "USD",
    "cart_amount": "500.00",
    "return": "https://example.com/order/10001",
    "redirect_url": "https://secure-egypt.paytabs.com/payment/page/599B792482E5A2AB2A3E8373265BA2963700A06113BC510285887ED7",
    "serviceId": 2,
    "profileId": 987654,
    "merchantId": 123456,
    "trace": "PMNT0404.6368BC3D.000BAF4C"
}

The Expected Parameter Behaviors


While the payment workflow proceeds with redirecting the customer to the Paytabs or/and issuer side for transaction authentication in the below listed ordered steps:

  • The customer/cardholder would enter his card details and submit the "PAY NOW" button.
  • Usually, if the card details are valid, the customer would be redirected to the issuer bank 3DSecure page to authenticate using the card.
  • After that, the customer would be redirected to the return page as you provided on the initial request, whatever the transaction status.

 

One of the following behaviors (according to the passed "return" value) will occur. The expected behaviors according to the passed value are:



  • Passing an HTTPS return URL

    In this case, the redirection will be performed in a POST HTTP request with brief transaction information, as shown below:
    acquirerMessage=&acquirerRRN=&cartId=CART%231001&customerEmail=mohammed.elrayes%40paytabs.com&respCode=G10046&respMessage=Authorised&respStatus=A&signature=3701705571119d23923a8677db0d5ae9086988c02b9bbfd354f80d84954d2f9a&token=&tranRef=TST2231101374414


    acquirerMessage  (empty)
acquirerRRN  (empty)
cartId  CART#1001
customerEmail  [email protected]
respCode  G10046
respMessage  Authorised
respStatus  A
signature  3701705571119d23923a8677db0d5ae9086988c02b9bbfd354f80d84954d2f9a
token  (empty)
tranRef  TST2231101374414

    This brief response can 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.



  • Passing a Non-HTTPS return URL


    As for this case, the customer will be redirected to the provided return URL via a GET request in which nobody (transaction response) will be included.



  • Not Passing any Return URL


    Finally, in case of not passing any return URL, the PayTabs' default post-payment behavior will be performed according to the status of the payment as clarified below:

    • A Successful Transaction





    • A Failed/Not-Completed Transaction