Skip to main content

Initiating The Payment

An invoice is a document you send to your client after purchasing goods or services from you, both as a means of recording the sale and requesting payment from them. You can catch everything you need about PayTabs invoices in our solutions article: What is PayTabs Invoice?

Invoices Payment Page integration type is suitable for merchants with PCI SAQ A or merchants does not have any PCI levels as it follows Hosted Payment page mechanism. To customize the UI of the Invoices payment page, check this article, and to know more about the Invoices Payment Page PCI DSS merchant requirements, please check this article.

The Available Endpoints to Initiate an Invoice​

In this manual, we'll guide you through initiating a payment request using this integration type. You'll learn about the necessary parameters required for the request and all the optional parameters available. You can choose to initiate the payment in one of two ways: via Payment or via Invoices. We strongly recommend reviewing theInvoice Payment Page | Payment Workflowmanual first to understand the business logic behind this integration.

As mentioned above, there are two ways you can use in the endpoints for initiating the invoice as clarified below:

  1. Invoice Endpoint
  2. Payment Endpoint

Each endpoint has a different flow and support different kind of parameters, you can choose one that suits your business needs best. In the upcoming section we will walk you through these 2 endpoints in detail.


Initiating an Invoice via Invoice Endpoint

Initiating an Invoice via Invoice Endpoint​

Here, we will walk you through the steps to initiate an invoice using the Invoice Endpoint. This dedicated interface simplifies the process of invoice creation and management, handling all aspects from generating new invoices to tracking payments and managing customer data. In this manual, we will provide a step-by-step guide to help you streamline your invoicing procedures and improve financial accuracy.


In this section, we will rely on the PayTabs Invoice 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/invoice/new
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/invoice/new

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 new invoice, you need - in addition to the general required above parameters - to include new parameters required specifically for the Invoices. Find below the Additional required parameters for the Invoice:

ParameterData TypeMinMaxRequired
invoice
OBJECTAt least "line_items" must be included✔
This is the main object that holds other parameters related to invoice creation. Including this in your request is considered the main flag to be treated as an Invoice creation request, not a normal hosted payment page request.
To know more about this parameter pleaseclick here. 
{
    "invoice": {
       }
}
invoice.line_items
OBJECT
At least one item must be included
✔
This is an array of the invoice objects/items that your customer purchased. Each item will be an object that holds its specific details.
To know more about this parameter pleaseclick here. 
{
    "invoice": {
        "line_items": [
            {
            }
        ]
   }
}
line_items.unit_cost
DECIMAL
0.1
9999999999.99
✔
This is an array of the invoice objects/items that your customer purchased. Each item will be an object that holds its specific details.
To know more about this parameter pleaseclick here. 
{
    "invoice": {
        "line_items": [
            {
                "unit_cost": 9.5,
            }
        ]
    }
}
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 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": **Your profile ID**,
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_description": "Description of the items/services",
    "cart_id": "Unique order reference00",
    "cart_amount": 100,
    "cart_currency": "SAR",
    "invoice": {
        "line_items": [
            {
                "unit_cost": 100,
                "quantity":2,
            }
        ]
    }
}

The Payment Page Experience​

Reaching this point, you are now able to initiate an Invoice API request and as you now, the process involves several key steps that ensure a smooth payment and tracking experience for both you and customers. Here’s how it works:

  1. Initiating the Request: Once you initiate a payment request, you will receive a response that includes a redirect URL. This URL is crucial for guiding your customer through the payment process.

    "invoice_link": "https://secure.PayTabs.sa/payment/request/invoice/2072841/A8CB6A4667A444E79E868206DB76382A",

  2. Redirecting the Customer: You should redirect your customer to this URL as you normally would in a payment transaction. This step allows the customer to complete their payment securely and efficiently. Below are the resulted payment page that your customer will be redirected to:

    Sample Payment Page

  3. Tracking in the Merchant Dashboard: After the payment is completed, the transaction will be displayed in your Merchant Dashboard. You can view the details of it in the transaction view.

This process ensures that you have full visibility and control over your split payouts, from initiating the transaction to tracking its completion in the dashboard.

Initiating an Invoice via Payment Endpoint

Initiating an Invoice via Payment Endpoint​

Here, we will walk you through the process of creating invoices efficiently using the Payment Endpoint. This endpoint offers a streamlined way to initiate invoices directly through your payment processing system. By leveraging this endpoint, businesses can automate the invoicing process, ensuring timely and accurate billing. This guide will highlight key features and best practices to optimize your workflow.


In this section, we will rely on the PayTabs Invoice 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
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 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 new invoice, you need - in addition to the general required above parameters - to include new parameters required specifically for the Invoices. Find below the Additional required parameters for the Invoice:

ParameterData TypeMinMaxRequired
invoice
OBJECTAt least "line_items" must be included✔
This is the main object that holds other parameters related to invoice creation. Including this in your request is considered the main flag to be treated as an Invoice creation request, not a normal hosted payment page request.
To know more about this parameter pleaseclick here. 
{
    "invoice": {
       }
}
invoice.line_items
OBJECT
At least one item must be included
✔
This is an array of the invoice objects/items that your customer purchased. Each item will be an object that holds its specific details.
To know more about this parameter pleaseclick here. 
{
    "invoice": {
        "line_items": [
            {
            }
        ]
   }
}
line_items.unit_cost
DECIMAL
0.1
9999999999.99
✔
This is an array of the invoice objects/items that your customer purchased. Each item will be an object that holds its specific details.
To know more about this parameter pleaseclick here. 
{
    "invoice": {
        "line_items": [
            {
                "unit_cost": 9.5,
            }
        ]
    }
}
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 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": "987###",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "SAR",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",
}

The Payment Page Experience​

Reaching this point, you are now able to initiate an Invoice through the payment endpoint API request and as you now, the process involves several key steps that ensure a smooth payment and tracking experience for both you and customers. Here’s how it works:

  1. Initiating the Request: Once you initiate a payment request, you will receive a response that includes a redirect URL. This URL is crucial for guiding your customer through the payment process.

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",

  2. Redirecting the Customer: You should redirect your customer to this URL as you normally would in a payment transaction. This step allows the customer to complete their payment securely and efficiently. Below are the resulted payment page that your customer will be redirected to:

    Sample Payment Page

  3. Tracking in the Merchant Dashboard: After the payment is completed, the transaction will be displayed in your Merchant Dashboard. You can view the details of it in the transaction view.

This process ensures that you have full visibility and control over your split payouts, from initiating the transaction to tracking its completion in the dashboard.