PayTabs Support Portal

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.

Tokenization is the process of protecting sensitive data by replacing it with an algorithmically generated number called a token. This can be used to allow returning customers to purchase without re-entering credit card details (recurring), such as monthly subscription fees. In this article, we will walk you through the series of steps you need to create a token via our API payment request.

In this article, you will be going to know about:

• The Endpoint and Related Postman Collection
• Create a Payment Request
• The Required Parameters
  • Sample Request Payload
  • Sample Response Payload
    • Sample Response Payload via Return
    • Sample Response Payload via Callback/IPN

The Endpoint and Related Postman Collection

In this tutorial, we will rely on the PayTabs invoices API Endpoint, mentioned on the PayTabs API endpoints postman collection, which you can access from here. The endpoint will need to be accessed with a POST request on the below-mentioned URL

Or

Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find the your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.

Create a Payment Request

The first thing you need to create a token is to create a basic payment request with the required information via any integration type that suits your business needs more, as mentioned in the previous step, "Step 3.2 - Initiating the Payment Request", but with including the below parameters as a MUST among the original request payload.

The Required Parameters

To initiate a tokenized payment request, you need to include these parameters to allow PayTabs to tokenize the customer card and send you this token back in the response. The specification of these required parameters is clarified below:

Note that in order for you to recieve the tokenized details you need to include either th "return" or the "call_back" parameters. You can learn more about them in our What is the Return URL vs the Callback URL solution article

Sample Request Payload

The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.

{
  "profile_id": "profile_id",
  "tran_type": "sale",
  "tran_class": "ecom",
  "cart_id": "cart_11111",
  "tokenise": "2",
  "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"
  }
}

Sample Response Payload

{
    "tran_ref": "TST2105900091503",
    "tran_type": "Sale",
    "cart_id": "cart_444441",
    "cart_description": "Payment with tok enabled, save card enabled",
    "cart_currency": "EGP",
    "cart_amount": "1",
    "callback": "https://webhook.site/ebe60b53-4158-4d82-aa16-231f2823378d",
    "return": "http://localhost/default/checkresponse.php",
    "redirect_url": "https://secure-egypt.paytabs.com/payment/page/3F3856B482E417B4D619EA58B2F511BACCCB35681E2A0DD91F1E6103",
    "customer_details": {
        "name": "first last",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "DU",
        "country": "AE"
    },
    "shipping_details": {
        "name": "name1 last1",
        "email": "[email protected]",
        "phone": "971555555555",
        "street1": "street2",
        "city": "dubai",
        "state": "DU",
        "country": "AE"
    }
}

acquirerMessage=
&acquirerRRN=
&cartId=cart_11111
&customerEmail=email%40domain.com
&respCode=G20348
&respMessage=Authorised
&respStatus=A
&token=2C4651BF67A3EC34C6B691FB638B7BBC
&tranRef=TST2111000149667
&signature=237d6d2067094366864e093692dfdaa1762f5da4e2265f7374cf37e8be969f38

Sample Response Payload via Callback/IPN

If the callback URL or IPN service is enabled, the sent JSON response will have the token, as shown below

{
  "tran_ref": "TST2111000149667",
  "merchant_id": 3469,
  "profile_id": 65945,
  "cart_id": "cart_11111",
  "cart_description": "Description of the items/services",
  "cart_currency": "USD",
  "cart_amount": "200.00",
  "tran_currency": "USD",
  "tran_total": "200.00",
  "tran_type": "Sale",
  "tran_class": "ECom",
  "customer_details": {
    "name": "first last",
    "email": "[email protected]",
    "phone": "0522222222",
    "street1": "address street",
    "city": "dubai",
    "state": "DU",
    "country": "AE",
    "ip": "196.219.145.121"
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "G20348",
    "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2021-04-20T12:05:48Z"
  },
  "payment_info": {
    "payment_method": "Visa",
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111",
    "expiryMonth": 11,
    "expiryYear": 2023,
    "IssuerCountry": "",
    "IssuerName": ""
  },
  "token": "2C4651BF67A3EC34C6B691FB638B7BBC"
}

⌂ 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 previous step "Step 2 - Configure the integration method" kindly click here.

⇦ And to get familiar with the rest of the steps regarding the current step "Step 3 - Initiating the payment" click here. 

⇨ And to navigate to the next step in the integration process "Step 4 - Accepting the payment" kindly click here.