Skip to main content

Initiating The Payment

Own Form integration type is suitable for merchants with PCI SAQ D-Merchant to know more about the Hosted Payment Page PCI DSS merchant requirements, please check this article .



In this manual, we will walk you through how to initiate a payment request via this integration type. You will be introduced to the required parameters that need to be passed to initiate the request, along with all the possible optional parameters as well. We highly recommend that you and your team check the "Payment Workflow" manual first to understand the business/logic this integration type relay on.


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

POST{{domain}}payment/request
caution

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_link.

POST{{domain}}payment/request
https://secure.paytabs.com/{{endpoint_uri}}

For example: https://secure.paytabs.com/payment/request


Request Parameters​

To initiate a payment request using this integration type, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below:

ParameterData TypeMinMaxRequired
profile_id
INTAccept only valid profile number✔
The merchant Profile ID you can get from your PayTabs dashboard. For more information please check ourHow to get your account information from PT2 Dashboard?tutorial article.
To know more about this parameter pleaseclick here.
{
    "profile_id": 987654
}
tran_type
STRING

Valid string from this enum list:

sale auth refund register void 		✔
the identification of the type of the transaction. To know more about these types please check ourWhat is the "tran_type" (transaction type)?solution article.
To know more about this parameter pleaseclick here.
{
    "tran_type": "sale"
}
tran_class
STRING

Valid string from this list

ecom recurringmoto		✔
the identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check ourWhat is the "tran_class" (transaction class)?solution article.
To know more about this parameter pleaseclick here.
{
     "tran_class": "ecom"
}
cart_id
STRING
1
64
✔
Indicates the cart/order id at the merchant end to easily relate the transaction to.
To know more about this parameter pleaseclick here.
{
     "cart_id": "CART#10001"
}
cart_description
STRING
1
128
✔
Indicates the cart/order description at the merchant end to easily relate the transaction to.
To know more about this parameter pleaseclick here.
{
     "cart_description": "Description of the items/services"
}
cart_currency
STRINGValid string from the following list:
SAR AED BHDEGP EUR GBP HKD IDR INR IQD JOD JPY KWD MAD OMR PKR QAR USD
Accepts both upper- and lower-case characters		✔
Indicates the transaction currency, which the customer will be charged with.
To know more about this parameter pleaseclick here.
{
     "cart_currency": "SAR"
}
cart_amount
DECIMAL
0.01
9999999999.99
✔
Indicates the amount of the transaction the customer is about to be charged Both min and max values are subjected to the merchant transaction limits.
To know more about this parameter pleaseclick here.
{
     "cart_amount": 500
}

Now in order to create a payment request through the Own Form, you need - in addition to the general required above parameters - to include new parameters required specifically for the Own Form. Find below the Additional required parameters for Own Form:

ParameterData TypeMinMaxRequired
card_details
OBJECTAccept only valid card details.✔
{
     "card_details": {
        "pan": "4111111111111111",
        "cvv": "123",
        "expiry_month": 12,
        "expiry_year": 2032
    }
}
card_details.pan
STRING
16
-
✔
{
    "card_details": {
        "pan": "4111111111111111"
    }
}
card_details.cvv
STRING
Valid CVV/CVC
✔
{
    "card_details": {
        "cvv": "123",
    }
}
card_details.expiry_month
INT
Valid expiry month between 01-12
✔
{
    "card_details": {
        "expiry_month": 12
    }
}
card_details.expiry_year
INT
Valid expiry year
✔
{
    "card_details": {
        "expiry_year": 2022
    }
}
customer_details
OBJECT
-
-
✔
Indicates the customer details for this payment.
To know more about this parameter pleaseclick here. 
{
    "customer_details": {
        "name": "Technical Support",
        "email": "demo@paytabs.com",
        "phone": "+966 55 xxxxxx6",
        "street1": "address street",
        "city": "Jeddah",
        "state": "Makkah",
        "country": "SA",
        "zip": "12345"
    }
}
customer_details.name
STRING
3
128
✔
{
    "customer_details": {
        "name": "Technical Support"
    }
}
customer_details.email
STRING
Valid email format
✔
{
    "customer_details": {
        "email": "demo@paytabs.com",
    }
}
customer_details.phone
STRING
Valid number + country code prefix
✔
{
    "customer_details": {
        "phone":"+966 55 xxxxxx6",
    }
}
customer_details.street1
STRING
3
128
✔
{
    "customer_details": {
        "street1": "address street",
    }
}
customer_details.city
STRING
City Code or City name
✔
{
    "customer_details": {
        "city": "Riyadh",
    }
}
customer_details.state
STRING
State/Province Code or State/Province name
✔
{
    "customer_details": {
        "state": "Makkah",
    }
}
customer_details.country
STRING
ISO 3166-1 alpha-2 codes (two-letter country codes)
✔
{
    "customer_details": {
        "country": "SA",
    }
}
customer_details.zip
STRING
Valid zip code
✔
{
    "customer_details": {
        "zip": "12345"
    }
}
customer_details.ip
STRING
Valid IP Address
✔
{
    "customer_details": {
        "ip": "37.104.xxx.xxx"
    }
}

Request & Response Payload Samples​

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.

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

{
"profile_id": "9876543",
"tran_type": "sale",
"tran_class": "ecom",
"cart_id": "CART#1001",
"cart_currency": "USD",
"cart_amount": 500,
"cart_description": "Description of the items/services",
"customer_details": {
"name": "Technical Support Team",
"email": "demo@payTabs.com",
"phone": "+201234567890",
"street1": "address street",
"city": "Cairo",
"state": "CAI",
"country": "EG",
"zip": "45555",
"ip": "1.1.1.1"
},
"card_details": {
"pan": "4111111111111111",
"cvv": "123",
"expiry_month": 12,
"expiry_year": 2023
}
}

Expected Payment Flow Behavior​

  1. As mentioned above in the How to use? section, As a merchant you would initiate a payment request per the above Specifications, same as the sample codes mentioned in the samples section above.

  2. Then, you will receive a response that includes redirect URL. This means you have initiated a correct payment request/page successfully.

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",
  3. Then, your customer will be redirected to his issuer bank 3DS/OTP page to authenticate the used card

  4. Finally, he would be redirect to a success/error page accordingly. And now, you will be able to see his transaction on your merchant dashboard, whether it's accepted/authorized or not.


    transaction view

    transaction view