Hosted Payment Page solution is suitable for Merchants with PCI SAQ A or merchants does not have any PCI levels. To customize the UI of the hosted payment page check this article, and to know more about PCI and PCI DSS merchant requirements please check this article.


In this article you will be going to know about:


Postman Endpoint Example


For the purposes of this article, you will need to use the following postman endpoint example for testing and integrating, for proceeding with this please click here



Payment Flow

  1. The Hosted Payment page uses Transaction API request which will return a response with a payment page link.
  2. The merchant should navigate the customers to this previous payment page link; in order to complete the payment.
  3. Once the payment is completed, PayTabs will redirect the customer back to the merchant’s website, to the return URL which was specified by the merchant in the API request and the payment results will be posted to that URL



    The Request Mandatory Payload (Body) Parameters

    1- Transaction type (tran_type)


    ValueDescription
    salePurchase Transaction
    authTransaction in auth and capture mode
    captureCapturing authorized transaction
    voidVoiding authorized transaction
    refundRefund Transaction of fully captured transaction


    2- Transaction class (tran_class)


    ValueDescription
    ecomECommerce Online Transaction
    motoMail Order Telephonic Order Transaction
    recurringRecurring token-based transaction


    Request Payload


    You will need to initiate your call to the following endpoint URL, with the following request payload example.

    Post{{domain}}/payment/request
    {
      "profile_id": 49622,
      "tran_type": "sale",
      "tran_class": "ecom",
      "cart_id": "cart_11111",
      "cart_description": "Description of the items/services",
      "cart_currency": "EGP",
      "cart_amount": 100,
      "return": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218"
    }

    Response Payload


    If the payment page is created successfully, you will receive an HTTP 200 OK response such as shown below including the payment page URL returned in a called redirect_url param.


    You should navigate your customer to this URL to complete the payment

    {
      "tran_ref": "TST2110300142699",
      "tran_type": "Sale",
      "cart_id": "cart_11111",
      "cart_description": "Description of the items/services",
      "cart_currency": "EGP",
      "cart_amount": "100.00",
      "return": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218",
      "redirect_url": "https://secure-egypt.paytabs.com/payment/page/3F76B62E82E417E6AB2104212437A16EA53E657E75232A6C4C544962"
    }

    Post Payment Process


    Once the payment is completed, the user will be redirected back to the URL passed to the “return” parameter in the request payload.


    The return URL must be HTTPS, in order to receive the payment result details.


     The payment result details will be posted to the “return” URL, as the example shown below:

    acquirerMessage= 
    &acquirerRRN= 
    &cartId=cart_11111 
    &customerEmail=aliaa%40paytabs.com 
    &respCode=G96376 
    &respMessage=Authorised 
    &respStatus=A 
    &token= 
    &tranRef=TST2110400143785 
    &signature=db333934b8bd8d5f94d90ab28c72831d563dc10bb196ebd78a300af7df8fad7

    The Request Optional Payload (Body) Parameters

    The following are optional parameters that could be added in the main request payload in the merchant calls.


    Framed Hosted Payment Page

    To display the hosted payment page in an embed frame within the merchant website itself, the following parameter must be passed in the request payload.

    "framed": true

    Payment Page Language


    The payment page can support either English (default) or Arabic language. So to create a payment page in the Arabic language you will need to pass the following parameter in your payload.

    "paypage_lang": "ar"


    Customer, Billing, and Shipping Details

    The following are optional parameters and additional sections that can be added in addition to the main request payload. 


    Pre-filled Customer, Billing, and Shipping Details

    Passing the following parameters will display billing/shipping sections prefilled and collapsed on the payment page.

    {
      "customer_details": {
        "name": "first last",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "du",
        "country": "AE",
        "zip": "12345",
        "ip": "1.1.1.1"
      },
      "shipping_details": {
        "name": "name1 last1",
        "email": "[email protected]",
        "phone": "971555555555",
        "street1": "street2",
        "city": "dubai",
        "state": "dubai",
        "country": "AE",
        "zip": "54321",
        "ip": "2.2.2.2"
      }
    }

    Hide Shipping Details


    In some cases that you will have digital products among your provided services to the customers, and you don’t require shipping details from your customers. You will not need to pass shipping details in the API request, you will just hide them from the created Hosted payment page by passing the following optional parameter in the main request payload of Transaction API

    "hide_shipping": true


    Hide Billing Details


    To hide both billing and shipping details, you will need to (at least) pass the full valid customer details in addition to passing the following parameter: “hide_shipping”: true

    {
      "profile_id": "profile_id",
      "tran_type": "sale",
      "tran_class": "ecom",
      "cart_id": "cart_11111",
      "cart_currency": "USD",
      "cart_amount": 200,
      "cart_description": "Description of the items/services",
      "return": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218",
      "callback": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218",
      "hide_shipping": true,
      "customer_details": {
        "name": "first last",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "du",
        "country": "AE",
        "zip": "12345",
        "ip": "1.1.1.1"
      }
    }


    The customer details are still required and must be passed in the API request and in case any of the details are missing or passed with invalid values; the hide_shipping option will be ignored and cardholder will be required to enter any of the missing details on the payment page


    Only shipping details are optional and may not be passed in the API request (such as digital products case)