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 PayTabs Postman APIs Collection. The endpoint will need to be accessed with a POST request on the below-mentioned URL

POST{{domain}}/payment/request
Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

https://secure.paytabs.sa/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 our How to get your account information from PT Dashboard? solution article. To know more about this parameter please click here.
{
    "profile_id": 987654
}
tran_type
STRING

Valid string from this enum list:

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

Valid string from this list

ecom recurring moto		✔
The identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check our What is the "tran_class" (transaction class)? solution article.
To know more about this parameter please click here.
{
     "tran_class": "ecom"
}
cart_id
STRING164✔
Indicates the cart/order id at the merchant end, to easily relate the PayTabs transaction to.
To know more about this parameter please click here.
{
     "cart_id": "CART#10001"
}
cart_description
STRING1128✔
Indicates the cart/order description at the merchant end, to easily relate the PayTabs transaction to.
To know more about this parameter please click here.
{
     "cart_id": "CART#10001"
}
cart_currency
STRING1128✔
Indicates the transaction currency, which the customer will be charged with.
To know more about this parameter please click here.
{
     "cart_currency": "SAR"
}
cart_amount
DECIMAL0.019999999999.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 please click here.
{
     "cart_amount": 500.99
}
customer_details
OBJECT✔
Indicates the customer details for this payment. If provided, the payment page will be prefilled with the provided data.
To know more about this parameter please click here.
{
    "customer_details": {
        "name": "first last",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "du",
        "country": "AE",
        "zip": "12345"
    }
}
customer_details's Nested Parameters
Nested ParameterData TypeMinMaxRequired
name
STRING3128✔
email
STRINGN/AN/A✔
phone
STRINGN/AN/A✔
street1
STRING3128✔
city
STRING3128✔
state
STRING22✔
country
STRINGN/AN/A✔
zip
STRINGN/AN/A✔
card_details
OBJECTAccept only valid card details.✔
card_details is one of the mandatory parameters exclusively for the Own-Form that the request should have, which indicates the card details.
{ 
    "card_details": {
        "pan": "4111111111111111",
        "cvv": "123",
        "expiry_month": 12,
        "expiry_year": 2028
    }
}
card_details's Nested Parameters
Nested ParameterData TypeMinMaxRequired
pan
STRING16N/A✔
Indicates the bank card number.
cvv
STRINGN/AN/A✔
Indicates to Card Verification Value/Code mainly located on the back of your credit/debit card on the right side of the white signature strip.
expiry_month
INTEGERN/AN/A✔
Indicates to Bank Card expiry month.
expiry_year
INTEGERN/AN/A✔
Indicates to Bank Card expiry year.

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 parameters, which are needed to be passed with valid values to perform a request.

{
    "profile_id": "9876543",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "SAR",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",
    "customer_details": 
    {
        "name": "Technical Support Team",
        "email": "[email protected]",
        "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. You will collect the customer's card details through your own form, making sure to follow the correctSpecificationssection and include the necessary request payload same as the sample codes mentioned in the samples section above.

  2. Card Authentication Check
    • If the card is not 3D Secure (3DS), the payment will proceed immediately without any further redirects.
    • If the card is 3D Secure, the payment request will include a, redirect URL, in the response, as the following
      • "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",
  3. Redirect to 3DS Authentication (If Applicable):
    • If the response includes a redirect URL, this means the card is 3D Secure, and the customer will be redirected to their issuer’s 3DS/OTP page to complete the authentication process
  4. Return to Merchant's Page
    • After completing the authentication, the customer will be redirected back to your return URL, where they will see the result of the payment attempt

  5. Finally, you will be able to see his transaction on your merchant dashboard, whether it's accepted/authorized or not.


    transaction view

    transaction view

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.