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

---

The Endpoint and Related Postman Collection

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 PayTabs Postman APIs Collection. 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.

KSA

https://secure.paytabs.sa/payment/invoice/new

UAE

https://secure.paytabs.com/payment/invoice/new

Egypt

https://secure-egypt.paytabs.com/payment/invoice/new

Oman

https://secure-oman.paytabs.com/payment/invoice/new

Jordan

https://secure-jordan.paytabs.com/payment/invoice/new

Kuwait

https://secure-kuwait.paytabs.com/payment/invoice/new

Global

https://secure-global.paytabs.com/payment/invoice/new

---

Request Parameters

The Minimum Required 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:

Parameter	Data Type	Min	Max	Required
profile_id	INT	Accept 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 PT2 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	STRING	1	64	✔
	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	STRING	1	128	✔
	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	STRING	1	128	✔
	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	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 please click here.
	{ "cart_amount": 500.99 }
invoice	OBJECT	At 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.
	{ "invoice": { ... } }
invoice's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
lang	STRING	N/A	N/A	✔
	This is parameter will define the invoice page languages.
	{ "invoice": { "lang":"ar" } }
disable_edit	BOOLEAN	N/A	N/A	✔
	This parameter will disable editing the invoice through the merchant dashboard.
	{ "invoice": { "shipping_charges": 0 }}
shipping_charges	DECIMAL	0.01	9999999999.99	✔
	Indicates the shipping charges that the merchant would add to the total invoice amount if he or she has shippable items.
	{ "Invoice":{ "disable_edit": true, } }
extra_charges	DECIMAL	0.01	9999999999.99	✔
	Indicates any extra charges that the merchant would add to the total invoice amount.
	{ "invoice": { "extra_charges": 0 }}
extra_discount	DECIMAL	0.01	9999999999.99	✔
	Indicates an extra discount that the merchant would exclude from the total invoice amount.
	{ "invoice": { "extra_discount": 0 }}
total	DECIMAL	0.01	9999999999.99	✔
	Indicates the total amount of the invoice which equals the total price of line_items plus shipping_charges + extra_charges minus extra_discount. Notes that if left as 0 or null it will be auto-calculated.
	{ "invoice": { "total": 0 }}
activation_date	DATE	N/A	N/A	✔
	Indicates the invoice activation date, which will make the invoice unavailable before this date.
	{ "invoice": { "activation_date":"2024-09-27T13:33:00+04:00" }}
expiry_date	DATE	N/A	N/A	✔
	Indicates the invoice expiry date which will make the invoice unavailable after this date.
	{ "invoice": { "expiry_date": "2025-09-27T13:33:00+04:00" }}
due_date	DATE	N/A	N/A	✔
	Indicates the invoice due date which will make the invoice unavailable before this date.
	{"invoice":{ "due_date": "2025-09-26T12:36:00+04:00", }}
line_items	OBJECT	N/A	N/A	✔
	This is an array of the invoice objects/items that your customer purchased. Each item will be an object that holds its specific details.
	{ "line_items": { "sku": "sku", "description": "desc", "url": "https://www.costacoffee.ae/whats-new/flat-white", "unit_cost": "9.5", "quantity": "1", "net_total": "9.5", "discount_rate": "0", "discount_amount": "0", "tax_total": "0", "total": "0" } }
line_items's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
unit_cost	DECIMAL	0.01	9999999999.99	✔
	Indicates this invoice item cost. It must be in the same currency passed already in the Initial Request Parameters.
quantity	INT	1	9999999999	✔
	Indicates the purchased quantity of this invoice item.
sku	STRING	N/A	N/A	✔
	Indicates the SKU of a certain item to be included with item details.
description	STRING	N/A	N/A	✔
	Indicates the item description to be included with the item details.
url	STRING	N/A	N/A	✔
	Indicates the item URL to be included with the item details.
net_total	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the net price of the current item without applying tax or discount.
discount_rate	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the discount rate for the current item. The rate is a percentage value that will be multiplied by the net price of the item and will be included in the total price of the item.
discount_amount	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the discount amount for the current item. This amount will be excluded.
tax_rate	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the tax rate for the current item to be included in the total price of the item.
tax_total	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the tax total for the current item to be included in the total price of the item.
total	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the total price of the current item to be included with the item details.

The Available Optional Parameters

Besides the above-mentioned required parameters, PayTabs provides you with several optional parameters, each of which empowers you with a different feature and the ability to customize your invoice payment request as much as possible it could be. The specification of these optional parameters is clarified below:

Parameter	Data Type	Min	Max	Required
return	STRING	N/A	255 Characters (Valid URL)	✘
	The return URL is the URL that PayTabs will redirect the customer to after he finishes the payment process (whether it's authenticated or not). It will redirect the customer with a POST response that is sent with the client/cardholder redirection through his browser containing the basic transaction information once the payment process ends (whether the customer cancels, paid, or failed to pay). It depends on the customer's actions, which means if the customer closes the browser right after the payment without waiting to be redirected back to your system, you will not receive this response. What is the Return URL vs the Callback URL? To know more about this parameter please click here.
	{ "return": "https://example.com/order/10001" }
callback	STRING	N/A	255 Characters (Valid URL)	✘
	The callback response is a server-to-server POST response that is sent (to a pre-defined HTTPS URL) with the full detailed transaction information once the payment process has ended (whether the customer cancels, paid, or failed to pay). It does not depend on the customer's actions; the response will be sent anyway. What is the Return URL vs the Callback URL? To know more about this parameter please click here.
	{ "callback": "https://www.example.com/notifications" }
hide_shipping	BOOLEAN			✘
	Indicates whether to hide shipping and billing information or not from the payment page. Note: The customer details are still required and must be passed in case any of the details are missing or passed with invalid values; the hide_shipping option will be ignored, and the cardholder will be required to enter any of the missing details on the payment page. To know more about this parameter please click here.
	{ "hide_shipping": true }
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 Parameter	Data Type	Min	Max	Required
name	STRING	3	128	✔
email	STRING	N/A	N/A	✔
phone	STRING	N/A	N/A	✔
street1	STRING	3	128	✔
city	STRING	3	128	✔
state	STRING	2	2	✔
country	STRING	N/A	N/A	✔
zip	STRING	N/A	N/A	✔
shipping_details	OBJECT			✘
	Indicates the customer shipping details for this payment. If provided, the payment page will be prefilled with the provided data..
	{ "shipping_details": { "name": "first last", "email": "[email protected]", "phone": "0522222222", "street1": "address street", "city": "dubai", "state": "du", "country": "AE", "zip": "12345" } }
shipping_details's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
name	STRING	3	128	✔
email	STRING	N/A	N/A	✔
phone	STRING	N/A	N/A	✔
street1	STRING	3	128	✔
city	STRING	3	128	✔
state	STRING	2	2	✔
country	STRING	N/A	N/A	✔
zip	STRING	N/A	N/A	✔
framed	BOOLEAN			✘
	Indicates whether to preview the payment page within the current check page instead of redirection or not. If ✔, preview the redirect URL sent in the response in '<iframe>' HTML tag, which will preview the whole payment page within this frame. To know more about this parameter please click here.
	{ "framed":true }
framed_return_top	BOOLEAN			✘
	Indicates whether to reload the whole page on redirections or just reload the current frame. To know more about this parameter please click here.
	{ "framed_return_top": true }
framed_return_parent	BOOLEAN			✘
	Indicates whether to reload the main base (could be div or another iFrame tag) that contained the payment page framed element. To know more about this parameter please click here.
	{ "framed_return_parent": true }
framed_message_target	URI	A valid HTTPS website URL of your domain (the recipient) that will receive the event. In order for the event to be dispatched, this domain must match exactly (including scheme, hostname, and port).		✘
	If you didn't have a return URL, PayTabs default return page (return: 'None'), to receive the message after the payment is done using the javascript, which gives your system the ability to close the iFrame after payment
	{ "framed_message_target": 'https://MERCHANT_WEBSITE.COM' }
paypage_lang	STRING	Either en or ar		✘
	Indicates the payment page displaying language. To know more about this parameter please click here.
	{ "paypage_lang": "en" }
config_id	INT	Valid Theme ID (from PayTabs dashboard)		✘
	Allows you to choose between your list of themes that have been created on your PayTabs dashboard. This chosen theme will be applied to the created payment page.
	{ "config_id": 2202 }
user_defined	OBJECT			✘
	For more customizations, you can pass to the Transaction API request your own "user-defined fields" up to 9 fields, and accordingly, you would receive those fields in the callback response. To know more about this parameter please click here.
	{ "user_defined": { "udf1": "UDF1 Test", "udf2": "UDF2 Test", "udf3": "UDF3 Test", "udf4": "UDF4 Test", "udf5": "UDF5 Test", "udf6": "UDF6 Test", "udf7": "UDF7 Test", "udf8": "UDF8 Test", "udf9": "UDF9 Test" } }
user_defined's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
udf1	STRING	1	255	✔
udf2	STRING	1	255	✔
udf3	STRING	1	255	✔
udf4	STRING	1	255	✔
udf5	STRING	1	255	✔
udf6	STRING	1	255	✔
udf7	STRING	1	255	✔
udf8	STRING	1	255	✔
udf9	STRING	1	255	✔
card_discounts	Array			✘
	To provide discounts for specific customers. To know more about this parameter please click here.
	{ "card_discounts":[ { "discount_cards":"41111,520000", "discount_amount": "30.00", "discount_title": "30.00 SAR discount on cards starts with 41111, 520000" }, { ..... } }
card_discounts's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
discount_cards	STRING	N/A	N/A	✔
	Provide a comma-separated list of card prefixes (usually first 6, can be up to first 11) To know more about this parameter please $1.
discount_title	STRING	N/A	N/A	✔
	Description of the discount that will be displayed for the customer on the hosted payment page. To know more about this parameter please $1.
discount_amount	DECIMAL	0.01	9999999999.99	✔
	The actual discount should be deducted from the cart_amount. To know more about this parameter please $1.
discount_percent	DECIMAL	0.01	100	✔
	The discount percentage that will be displayed for the customer on the hosted payment page. To know more about this parameter please $1.
card_filter	STRING	N/A	255 character	✘
	card_filter is one of the optional parameters that the request may have, which will allow you to accept only cards that start with a specific number/identifier/BIN code you want.
	{ "card_filter": "41111,400000,5200000,549838" }
tokenise	STRING	Pass one of the following list: 1 - no tokenization 2 - Hex32 3 - AlphaNum20 4 - Digit22 5 - Digit16 6 - AlphaNum32		✘
	The tokenization format the generated token should follow. Hosted Payment Page APIs | Token Based Transactions . To know more about this parameter please click here.
	{ "tokenise": 2, }
show_save_card	BOOLEAN			✘
	For showing the “save this card” option on the payment page. To know more about this parameter please click here.
	{ "show_save_card": 1 }
alt_currency	STRING	3 Characters	3 Characters	✘
	Indicates an alternative currency that you want to display your amount with it in your payment page. This will allow you to display the approximate amount of the payment cart amount in this alternative currency for this transaction..
	{ "alt_currency ":"SAR" }
payment_methods	STRING	Pass one or more of the following list: click here		✘
	To know more about this parameter please click here.
	{ "payment_methods": [ "applepay", "valu", "creditcard", "-meeza" ] }
token	STRING			✘
	To know more about this parameter please click here.
	{ "token": "2C4652BD67A3EF30C6B390F9668175B9" }
tran_ref	STRING			✘
	Indicates the Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref]
	{ "tran_ref": "TST2234701408XXX" }
generate_qr	BOOLEAN			✘
	If you set this parameter to true you will get a QR code image as encoded Base64 code within the response payload.
	{ "generate_qr": true }
token_info	OBJECT			✘
	To provide more customization on token, and modify it if you don't like to use the default one
	{ "token_info": { "token_type":"recurring_fixed", "payment_frequency": "MONTHLY", "min_amount_per_payment": "7.75" "max_amount_per_payment":"99.99", "min_days_between_payments":"2", "counter":"1", "total_count":"10", "start_date":"30-Sep-2024", "expiry_date":"31-Dec-2025", }
token_info's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
token_type	STRING	N/A	N/A	✔
	it shows if the token will be used in monthly subscription or will be used in unscheduled time, or subscription but not fixed time
payment_frequency	STRING	N/A	N/A	✔
	This is a response parameter that would specifics the payment frequency plan depending on how it's configured by the merchant.
min_amount_per_payment	DECIMAL	1	9999999999.99	✔
	indicates the minimum amount per transaction using the token created, it will be declined if the amount is less than this limit
max_amount_per_payment	DECIMAL	1	100	✔
	indicates the maximum amount per transaction using the token created, it will be declined if the amount is greater than this limit
counter	INT	1	999	✔
	indicates the payment iteration/cycle number among it's valid/configured maximum rounds/counts it should be. Note that this value is validated on the processor/bank side, PayTabs has no upper hand to validate the credibility of such information.
total_count	INT	1	999	✔
	indicates the maximum payments integration/cycles number. Note that this value is validated on the processor/bank side, PayTabs has no upper hand to validate the credibility of such information.
start_date	DATE	N/A	N/A	✔
	indicates the date of starting using the token, the token cannot be used before this date
expiry_date	DATE	N/A	N/A	✔
	Indicates the expiry date of the token
paymentChannel	STRING			✘
	this field detect shows which channel of integration/dashboard makes this transaction, this field will be returned in the IPN, callback and query transaction
	{ "paymentChannel":"WooCommerce" }
threeDSDetails	OBJECT			✘
	This object will contain 3Ds details of the card
	{ "threeDSDetails": { "responseLevel": 2, "responseStatus": 4, "enrolled": "Y", "paResStatus": "Y", "eci": "05", "cavv": "", "ucaf": "AAICAIVgwAAAIi4eEApdQAAAAA=", "threeDSVersion": "2.2.0" } }
threeDSDetails's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
responseLevel	INT	N/A	N/A	✔
	This parameter indicates the agreement description which you can use to distinguish your agreements and you can also use it as a title for your agreement.
responseStatus	STRING	N/A	N/A	✔
	#TODO#
enrolled	STRING	N/A	N/A	✔
	#TODO#
PaResStatus	STRING	N/A	N/A	✔
	#TODO#
Eci	STRING	N/A	N/A	✔
	#TODO#
cavv	STRING	N/A	N/A	✔
	CAVV is a cryptographic value generated during a 3D Secure transaction (e.g., Visa Secure, Mastercard Identity Check, AMEX SafeKey). It proves that authentication was performed by the cardholder.
ucaf	STRING	N/A	N/A	✔
	UCAF is a security field used to pass authentication data between merchants, payment processors, and card issuers.
threeDSVersion	STRING	N/A	N/A	✔
	This parameter shares 3Ds version which vary from card to another
trace_code	STRING			✘
	Trace code (trace) is the parameter that Indicates the code that PayTabs can trace this response with
	{ "trace_code":"PMNT0402.67B45334.00094965"
trace	STRING			✘
	Trace code (trace) is the parameter that Indicates the code that PayTabs can trace this response with
	{ "trace":"PMNT0404.6399E3D5.0000372C"
code	INT			✘
	This parameter is a status code, that shows the code of the error and will be followed with message field that clarify the error
	{ "code":2
message	STRING			✘
	This parameter is showing error message which is always shown after code parameter shown in the response
	{ "message":"Request must be in JSON format with content type application/json
pt_tran_ref	STRING			✘
	Indicates the same as Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref], but it's used for forsa refund transactions
	{ "pt_tran_ref": "TST2234701408XXX" }
forsa_tran_ref	STRING			✘
	it transaction reference related to forsa provider( payment method, it's differs from paytabs reference
	{ "forsa_tran_ref": ": 675451" }
refund_tran_ref	STRING			✘
	Indicates the same as Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref], but it's in the response of the refund of forsa #TODO#ADDFORSA ENDOINTHERE#
	{ "refund_tran_ref": "TST2234701408XXX" }
refunded_amount	DECIMAL	0.01	99999999.99	✘
	indicate the refunded amount from the normal detected transaction, means that you may partial refund not full
	{ "refunded_amount": 500 }
refunded	#boolean			✘
	boolean field indicates if the refund is done or not
	{ "refunded": "true" }
customer_ref	STRING			✘
	Indicates the customer reference that is provided from the merchant side.
	{ "customer_ref": "101" }
invoice_link	STRING			✘
	Indicates the link to which customers should be directed to complete their invoice payment.
	{ "invoice_id": 6745, "invoice_link": "https://secure.paytabs.com/payment/request/invoice/6745/09D332CFFD0D466186D36E3XXXXXXXXX", "trace_code": "PMNT9XXX.67286XXX.0000XXXX" }
payment_info	OBJECT			✘
	Indicates the form of payment information in detail.
	{ "payment_info": { "payment_method": "Visa", "card_type": "Credit", "card_scheme": "Visa", "payment_description": "4111 11## #### 1111", "expiryMonth": 12, "expiryYear": 2022 } }
payment_info's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
payment_method	STRING	N/A	N/A	✔
	The type of payment method used (e.g., 'Visa', 'Mastercard', 'ApplePay', 'Amex', etc).
card_type	STRING	N/A	N/A	✔
	Specifies whether the card is a 'Credit' or 'Debit' card. For all payments other than bank cards, this parameter will not be present.
card_schema	STRING	N/A	N/A	✔
	The card network or brand (e.g., 'Visa', 'Mastercard', 'Amex'). For all payments other than bank cards, this parameter will be empty.
payment_description	STRING	N/A	N/A	✔
	A masked representation of the card number for security purposes. For all payments other than bank cards, this parameter will shows the payment method name.
expiryMonth	INT	N/A	N/A	✔
	The expiration month of the card (1-12). For all payments other than bank cards, this parameter will not be present.
expiryYear	INT	N/A	N/A	✔
	The expiration year of the card (e.g., 2027). For all payments other than bank cards, this parameter will not be present.
issuerCountry	STRING	N/A	N/A	✔
	The two-letter country code (ISO 3166-1 alpha-2) of the payment method issuer (e.g., 'SA' for Saudi Arabia).
issuerName	STRING	N/A	N/A	✔
	The name of the financial institution that issued the card, or funded the installment plan (for example, 'Valu', 'Arab National Bank', etc)
contact_data	OBJECT			✘
	The main object containing contact transaction details.
	{ "contact_data": { "sessionId": "ZXJtGvFAhtWtKIPgSvmGwmMKKHsfolZFvDKPMETccGUvjvXQLTnDXXXXXXXXXXX", "invoiceNO": "546241", "client": "27610201XXXX", "items": [ { "itemId": "1932", "price": "900.00", "downPayment": "0", "tenor": "24", "adminFees": "0", "isBonus": "false" } ], "price": "900.00", "downPayment": "0" } }
contact_data's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
sessionId	STRING	N/A	N/A	✔
	A unique identifier for the transaction session.
invoiceNo	STRING	N/A	N/A	✔
	The invoice number for tracking the payment plan.
client	STRING	N/A	N/A	✔
	The unique identifier of the client (customer ID).
price	DECIMAL	N/A	N/A	✔
	The total price of all items in the installment plan.
downPayment	DECIMAL	N/A	N/A	✔
	The total down payment amount for all items.
items	Array	N/A	N/A	✔
	A list of items included in the contact transaction.
items's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
itemId	STRING	N/A	N/A	✔
	The unique identifier of the item being purchased.
price	DECIMAL	N/A	N/A	✔
	The total price of the item in the installment plan.
downPayment	DECIMAL	N/A	N/A	✔
	The initial amount paid upfront.
tenor	INT	N/A	N/A	✔
	The number of months (or installments) for repayment.
adminFees	DECIMAL	N/A	N/A	✔
	Any administrative fees associated with the plan.
isBonus	BOOLEAN	N/A	N/A	✔
	Indicates if the item qualifies for a bonus offer.
created_date_from	DATE	Required for search by page for a specific day, created_date_from and created_date_to should be the same date, date format DD/MM/YYYY		✘
	Show invoices resuts in a spicic date.
	{ "profile_id": "47157", "created_date_from": "01/11/2024", "created_date_to": "01/11/2024", "page": 2 }
created_date_to	DATE	Required for search by page for a specific day, created_date_from and created_date_to should be the same date, date format DD/MM/YYYY		✘
	Show invoices resuts in a spicic date.
	{ "profile_id": "47157", "created_date_from": "01/11/2024", "created_date_to": "01/11/2024", "page": 2 }
page	INT	This field is only accepted if the search request is by date range only (so no cart ID/customer ref etc), and the date range is a single day (so from and to date must be the same). The value for page can be between 1 and 20. If no page value is provided, then 1 is assumed.		✘
	Show invoices resuts in a spicic page.
	{ "profile_id": "47157", "created_date_from": "01/11/2024", "created_date_to": "01/11/2024", "page": 2 }
pager	OBJECT			✘
	this object will shows the paging paramters details
	{ "pager": { "page": 2, "pageSize": 500, "pageItems": 500, "totalItems": 1317 } }
pager's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
page	INT	N/A	N/A	✔
	the current page number
pageSize	INT	N/A	N/A	✔
	the max number of items per page
pageItems	INT	N/A	N/A	✔
	the actual number of items on this page
totalItems	INT	N/A	N/A	✔
	the total items available over all pages.

---

Request & Response Payload Samples

Required Parameters Sample Payloads

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.

Sample 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
            }
        ]
    }
}

Sample Response Payload

{
    "invoice_id": 2072841,
    "invoice_link": "https://secure.paytabs.com/payment/request/invoice/2072841/A8C678206DB76382A"
}

Optional Parameters Sample Payloads

The below sample request payload will show you how you can pass the above-mentioned optional 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.

Sample 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": 9.5,
    "cart_currency": "SAR",
    "invoice": {
        "lang": "en",
        "shipping_charges": 0,
        "extra_charges": 0,
        "extra_discount": 0,
        "total": 0,
        "activation_date": "",
        "expiry_date": "2024-09-27T13:33:00+04:00",
        "line_items": [
            {
                "sku": "sku",
                "description": "desc",
                "url": "https://www.costacoffee.ae/whats-new/flat-white",
                "unit_cost": 9.5,
                "quantity": 1,
                "net_total": 9.5,
                "discount_rate": 0,
                "discount_amount": 0,
                "tax_rate": 0,
                "tax_total": 0,
                "total": 9.5
            },
        ]
    },
    "customer_details": {
        "name": "first last",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "du",
        "country": "AE",
        "zip": "12345"
    },
    "shipping_details": {
        "name": "name1 last1",
        "email": "[email protected]",
        "phone": "971555555555",
        "street1": "street2",
        "city": "dubai",
        "state": "dubai",
        "country": "AE",
        "zip": "54321"
    },
    "user_defined": {
        "test": "UDF1 Test",
        "test2": "UDF2 Test",
        "udf3": "UDF3 Test",
        "udf4": "UDF4 Test",
        "udf5": "UDF5 Test",
        "udf6": "UDF6 Test",
        "udf7": "UDF7 Test",
        "udf8": "UDF8 Test",
        "udf9": "UDF9 Test"
    },
    "callback": "{{callback_url}}",
    "return": "{{return_url}}"
}

Sample Response Payload

{
    "invoice_id": 2072841,
    "invoice_link": "https://secure.paytabs.com/payment/request/invoice/2072841/A8CB6A868206DB76382A"
}

---

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.com/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:

   

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.

---

The Endpoint and Related Postman Collection

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

KSA

https://secure.paytabs.sa/payment/request

UAE

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

Egypt

https://secure-egypt.paytabs.com/payment/request

Oman

https://secure-oman.paytabs.com/payment/request

Jordan

https://secure-jordan.paytabs.com/payment/request

Kuwait

https://secure-kuwait.paytabs.com/payment/request

Global

https://secure-global.paytabs.com/payment/request

---

Request Parameters

The Minimum Required 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:

Parameter	Data Type	Min	Max	Required
profile_id	INT	Accept 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 PT2 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	STRING	1	64	✔
	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	STRING	1	128	✔
	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	STRING	1	128	✔
	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	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 please click here.
	{ "cart_amount": 500.99 }
invoice	OBJECT	At 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.
	{ "invoice": { ... } }
invoice's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
lang	STRING	N/A	N/A	✔
	This is parameter will define the invoice page languages.
	{ "invoice": { "lang":"ar" } }
disable_edit	BOOLEAN	N/A	N/A	✔
	This parameter will disable editing the invoice through the merchant dashboard.
	{ "invoice": { "shipping_charges": 0 }}
shipping_charges	DECIMAL	0.01	9999999999.99	✔
	Indicates the shipping charges that the merchant would add to the total invoice amount if he or she has shippable items.
	{ "Invoice":{ "disable_edit": true, } }
extra_charges	DECIMAL	0.01	9999999999.99	✔
	Indicates any extra charges that the merchant would add to the total invoice amount.
	{ "invoice": { "extra_charges": 0 }}
extra_discount	DECIMAL	0.01	9999999999.99	✔
	Indicates an extra discount that the merchant would exclude from the total invoice amount.
	{ "invoice": { "extra_discount": 0 }}
total	DECIMAL	0.01	9999999999.99	✔
	Indicates the total amount of the invoice which equals the total price of line_items plus shipping_charges + extra_charges minus extra_discount. Notes that if left as 0 or null it will be auto-calculated.
	{ "invoice": { "total": 0 }}
activation_date	DATE	N/A	N/A	✔
	Indicates the invoice activation date, which will make the invoice unavailable before this date.
	{ "invoice": { "activation_date":"2024-09-27T13:33:00+04:00" }}
expiry_date	DATE	N/A	N/A	✔
	Indicates the invoice expiry date which will make the invoice unavailable after this date.
	{ "invoice": { "expiry_date": "2025-09-27T13:33:00+04:00" }}
due_date	DATE	N/A	N/A	✔
	Indicates the invoice due date which will make the invoice unavailable before this date.
	{"invoice":{ "due_date": "2025-09-26T12:36:00+04:00", }}
line_items	OBJECT	N/A	N/A	✔
	This is an array of the invoice objects/items that your customer purchased. Each item will be an object that holds its specific details.
	{ "line_items": { "sku": "sku", "description": "desc", "url": "https://www.costacoffee.ae/whats-new/flat-white", "unit_cost": "9.5", "quantity": "1", "net_total": "9.5", "discount_rate": "0", "discount_amount": "0", "tax_total": "0", "total": "0" } }
line_items's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
unit_cost	DECIMAL	0.01	9999999999.99	✔
	Indicates this invoice item cost. It must be in the same currency passed already in the Initial Request Parameters.
quantity	INT	1	9999999999	✔
	Indicates the purchased quantity of this invoice item.
sku	STRING	N/A	N/A	✔
	Indicates the SKU of a certain item to be included with item details.
description	STRING	N/A	N/A	✔
	Indicates the item description to be included with the item details.
url	STRING	N/A	N/A	✔
	Indicates the item URL to be included with the item details.
net_total	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the net price of the current item without applying tax or discount.
discount_rate	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the discount rate for the current item. The rate is a percentage value that will be multiplied by the net price of the item and will be included in the total price of the item.
discount_amount	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the discount amount for the current item. This amount will be excluded.
tax_rate	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the tax rate for the current item to be included in the total price of the item.
tax_total	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the tax total for the current item to be included in the total price of the item.
total	DECIMAL	0.01	9999999999.99	✔
	This parameter indicates the total price of the current item to be included with the item details.

The Available Optional Parameters

Besides the above-mentioned required parameters, PayTabs provides you with several optional parameters, each of which empowers you with a different feature and the ability to customize your invoice payment request as much as possible it could be. The specification of these optional parameters is clarified below:

Parameter	Data Type	Min	Max	Required
return	STRING	N/A	255 Characters (Valid URL)	✘
	The return URL is the URL that PayTabs will redirect the customer to after he finishes the payment process (whether it's authenticated or not). It will redirect the customer with a POST response that is sent with the client/cardholder redirection through his browser containing the basic transaction information once the payment process ends (whether the customer cancels, paid, or failed to pay). It depends on the customer's actions, which means if the customer closes the browser right after the payment without waiting to be redirected back to your system, you will not receive this response. What is the Return URL vs the Callback URL? To know more about this parameter please click here.
	{ "return": "https://example.com/order/10001" }
callback	STRING	N/A	255 Characters (Valid URL)	✘
	The callback response is a server-to-server POST response that is sent (to a pre-defined HTTPS URL) with the full detailed transaction information once the payment process has ended (whether the customer cancels, paid, or failed to pay). It does not depend on the customer's actions; the response will be sent anyway. What is the Return URL vs the Callback URL? To know more about this parameter please click here.
	{ "callback": "https://www.example.com/notifications" }
hide_shipping	BOOLEAN			✘
	Indicates whether to hide shipping and billing information or not from the payment page. Note: The customer details are still required and must be passed in case any of the details are missing or passed with invalid values; the hide_shipping option will be ignored, and the cardholder will be required to enter any of the missing details on the payment page. To know more about this parameter please click here.
	{ "hide_shipping": true }
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 Parameter	Data Type	Min	Max	Required
name	STRING	3	128	✔
email	STRING	N/A	N/A	✔
phone	STRING	N/A	N/A	✔
street1	STRING	3	128	✔
city	STRING	3	128	✔
state	STRING	2	2	✔
country	STRING	N/A	N/A	✔
zip	STRING	N/A	N/A	✔
shipping_details	OBJECT			✘
	Indicates the customer shipping details for this payment. If provided, the payment page will be prefilled with the provided data..
	{ "shipping_details": { "name": "first last", "email": "[email protected]", "phone": "0522222222", "street1": "address street", "city": "dubai", "state": "du", "country": "AE", "zip": "12345" } }
shipping_details's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
name	STRING	3	128	✔
email	STRING	N/A	N/A	✔
phone	STRING	N/A	N/A	✔
street1	STRING	3	128	✔
city	STRING	3	128	✔
state	STRING	2	2	✔
country	STRING	N/A	N/A	✔
zip	STRING	N/A	N/A	✔
framed	BOOLEAN			✘
	Indicates whether to preview the payment page within the current check page instead of redirection or not. If ✔, preview the redirect URL sent in the response in '<iframe>' HTML tag, which will preview the whole payment page within this frame. To know more about this parameter please click here.
	{ "framed":true }
framed_return_top	BOOLEAN			✘
	Indicates whether to reload the whole page on redirections or just reload the current frame. To know more about this parameter please click here.
	{ "framed_return_top": true }
framed_return_parent	BOOLEAN			✘
	Indicates whether to reload the main base (could be div or another iFrame tag) that contained the payment page framed element. To know more about this parameter please click here.
	{ "framed_return_parent": true }
framed_message_target	URI	A valid HTTPS website URL of your domain (the recipient) that will receive the event. In order for the event to be dispatched, this domain must match exactly (including scheme, hostname, and port).		✘
	If you didn't have a return URL, PayTabs default return page (return: 'None'), to receive the message after the payment is done using the javascript, which gives your system the ability to close the iFrame after payment
	{ "framed_message_target": 'https://MERCHANT_WEBSITE.COM' }
paypage_lang	STRING	Either en or ar		✘
	Indicates the payment page displaying language. To know more about this parameter please click here.
	{ "paypage_lang": "en" }
config_id	INT	Valid Theme ID (from PayTabs dashboard)		✘
	Allows you to choose between your list of themes that have been created on your PayTabs dashboard. This chosen theme will be applied to the created payment page.
	{ "config_id": 2202 }
user_defined	OBJECT			✘
	For more customizations, you can pass to the Transaction API request your own "user-defined fields" up to 9 fields, and accordingly, you would receive those fields in the callback response. To know more about this parameter please click here.
	{ "user_defined": { "udf1": "UDF1 Test", "udf2": "UDF2 Test", "udf3": "UDF3 Test", "udf4": "UDF4 Test", "udf5": "UDF5 Test", "udf6": "UDF6 Test", "udf7": "UDF7 Test", "udf8": "UDF8 Test", "udf9": "UDF9 Test" } }
user_defined's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
udf1	STRING	1	255	✔
udf2	STRING	1	255	✔
udf3	STRING	1	255	✔
udf4	STRING	1	255	✔
udf5	STRING	1	255	✔
udf6	STRING	1	255	✔
udf7	STRING	1	255	✔
udf8	STRING	1	255	✔
udf9	STRING	1	255	✔
card_discounts	Array			✘
	To provide discounts for specific customers. To know more about this parameter please click here.
	{ "card_discounts":[ { "discount_cards":"41111,520000", "discount_amount": "30.00", "discount_title": "30.00 SAR discount on cards starts with 41111, 520000" }, { ..... } }
card_discounts's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
discount_cards	STRING	N/A	N/A	✔
	Provide a comma-separated list of card prefixes (usually first 6, can be up to first 11) To know more about this parameter please $1.
discount_title	STRING	N/A	N/A	✔
	Description of the discount that will be displayed for the customer on the hosted payment page. To know more about this parameter please $1.
discount_amount	DECIMAL	0.01	9999999999.99	✔
	The actual discount should be deducted from the cart_amount. To know more about this parameter please $1.
discount_percent	DECIMAL	0.01	100	✔
	The discount percentage that will be displayed for the customer on the hosted payment page. To know more about this parameter please $1.
card_filter	STRING	N/A	255 character	✘
	card_filter is one of the optional parameters that the request may have, which will allow you to accept only cards that start with a specific number/identifier/BIN code you want.
	{ "card_filter": "41111,400000,5200000,549838" }
tokenise	STRING	Pass one of the following list: 1 - no tokenization 2 - Hex32 3 - AlphaNum20 4 - Digit22 5 - Digit16 6 - AlphaNum32		✘
	The tokenization format the generated token should follow. Hosted Payment Page APIs | Token Based Transactions . To know more about this parameter please click here.
	{ "tokenise": 2, }
show_save_card	BOOLEAN			✘
	For showing the “save this card” option on the payment page. To know more about this parameter please click here.
	{ "show_save_card": 1 }
alt_currency	STRING	3 Characters	3 Characters	✘
	Indicates an alternative currency that you want to display your amount with it in your payment page. This will allow you to display the approximate amount of the payment cart amount in this alternative currency for this transaction..
	{ "alt_currency ":"SAR" }
payment_methods	STRING	Pass one or more of the following list: click here		✘
	To know more about this parameter please click here.
	{ "payment_methods": [ "applepay", "valu", "creditcard", "-meeza" ] }
token	STRING			✘
	To know more about this parameter please click here.
	{ "token": "2C4652BD67A3EF30C6B390F9668175B9" }
tran_ref	STRING			✘
	Indicates the Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref]
	{ "tran_ref": "TST2234701408XXX" }
generate_qr	BOOLEAN			✘
	If you set this parameter to true you will get a QR code image as encoded Base64 code within the response payload.
	{ "generate_qr": true }
token_info	OBJECT			✘
	To provide more customization on token, and modify it if you don't like to use the default one
	{ "token_info": { "token_type":"recurring_fixed", "payment_frequency": "MONTHLY", "min_amount_per_payment": "7.75" "max_amount_per_payment":"99.99", "min_days_between_payments":"2", "counter":"1", "total_count":"10", "start_date":"30-Sep-2024", "expiry_date":"31-Dec-2025", }
token_info's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
token_type	STRING	N/A	N/A	✔
	it shows if the token will be used in monthly subscription or will be used in unscheduled time, or subscription but not fixed time
payment_frequency	STRING	N/A	N/A	✔
	This is a response parameter that would specifics the payment frequency plan depending on how it's configured by the merchant.
min_amount_per_payment	DECIMAL	1	9999999999.99	✔
	indicates the minimum amount per transaction using the token created, it will be declined if the amount is less than this limit
max_amount_per_payment	DECIMAL	1	100	✔
	indicates the maximum amount per transaction using the token created, it will be declined if the amount is greater than this limit
counter	INT	1	999	✔
	indicates the payment iteration/cycle number among it's valid/configured maximum rounds/counts it should be. Note that this value is validated on the processor/bank side, PayTabs has no upper hand to validate the credibility of such information.
total_count	INT	1	999	✔
	indicates the maximum payments integration/cycles number. Note that this value is validated on the processor/bank side, PayTabs has no upper hand to validate the credibility of such information.
start_date	DATE	N/A	N/A	✔
	indicates the date of starting using the token, the token cannot be used before this date
expiry_date	DATE	N/A	N/A	✔
	Indicates the expiry date of the token
paymentChannel	STRING			✘
	this field detect shows which channel of integration/dashboard makes this transaction, this field will be returned in the IPN, callback and query transaction
	{ "paymentChannel":"WooCommerce" }
threeDSDetails	OBJECT			✘
	This object will contain 3Ds details of the card
	{ "threeDSDetails": { "responseLevel": 2, "responseStatus": 4, "enrolled": "Y", "paResStatus": "Y", "eci": "05", "cavv": "", "ucaf": "AAICAIVgwAAAIi4eEApdQAAAAA=", "threeDSVersion": "2.2.0" } }
threeDSDetails's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
responseLevel	INT	N/A	N/A	✔
	This parameter indicates the agreement description which you can use to distinguish your agreements and you can also use it as a title for your agreement.
responseStatus	STRING	N/A	N/A	✔
	#TODO#
enrolled	STRING	N/A	N/A	✔
	#TODO#
PaResStatus	STRING	N/A	N/A	✔
	#TODO#
Eci	STRING	N/A	N/A	✔
	#TODO#
cavv	STRING	N/A	N/A	✔
	CAVV is a cryptographic value generated during a 3D Secure transaction (e.g., Visa Secure, Mastercard Identity Check, AMEX SafeKey). It proves that authentication was performed by the cardholder.
ucaf	STRING	N/A	N/A	✔
	UCAF is a security field used to pass authentication data between merchants, payment processors, and card issuers.
threeDSVersion	STRING	N/A	N/A	✔
	This parameter shares 3Ds version which vary from card to another
trace_code	STRING			✘
	Trace code (trace) is the parameter that Indicates the code that PayTabs can trace this response with
	{ "trace_code":"PMNT0402.67B45334.00094965"
trace	STRING			✘
	Trace code (trace) is the parameter that Indicates the code that PayTabs can trace this response with
	{ "trace":"PMNT0404.6399E3D5.0000372C"
code	INT			✘
	This parameter is a status code, that shows the code of the error and will be followed with message field that clarify the error
	{ "code":2
message	STRING			✘
	This parameter is showing error message which is always shown after code parameter shown in the response
	{ "message":"Request must be in JSON format with content type application/json
pt_tran_ref	STRING			✘
	Indicates the same as Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref], but it's used for forsa refund transactions
	{ "pt_tran_ref": "TST2234701408XXX" }
forsa_tran_ref	STRING			✘
	it transaction reference related to forsa provider( payment method, it's differs from paytabs reference
	{ "forsa_tran_ref": ": 675451" }
refund_tran_ref	STRING			✘
	Indicates the same as Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref], but it's in the response of the refund of forsa #TODO#ADDFORSA ENDOINTHERE#
	{ "refund_tran_ref": "TST2234701408XXX" }
refunded_amount	DECIMAL	0.01	99999999.99	✘
	indicate the refunded amount from the normal detected transaction, means that you may partial refund not full
	{ "refunded_amount": 500 }
refunded	#boolean			✘
	boolean field indicates if the refund is done or not
	{ "refunded": "true" }
customer_ref	STRING			✘
	Indicates the customer reference that is provided from the merchant side.
	{ "customer_ref": "101" }
invoice_link	STRING			✘
	Indicates the link to which customers should be directed to complete their invoice payment.
	{ "invoice_id": 6745, "invoice_link": "https://secure.paytabs.com/payment/request/invoice/6745/09D332CFFD0D466186D36E3XXXXXXXXX", "trace_code": "PMNT9XXX.67286XXX.0000XXXX" }
payment_info	OBJECT			✘
	Indicates the form of payment information in detail.
	{ "payment_info": { "payment_method": "Visa", "card_type": "Credit", "card_scheme": "Visa", "payment_description": "4111 11## #### 1111", "expiryMonth": 12, "expiryYear": 2022 } }
payment_info's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
payment_method	STRING	N/A	N/A	✔
	The type of payment method used (e.g., 'Visa', 'Mastercard', 'ApplePay', 'Amex', etc).
card_type	STRING	N/A	N/A	✔
	Specifies whether the card is a 'Credit' or 'Debit' card. For all payments other than bank cards, this parameter will not be present.
card_schema	STRING	N/A	N/A	✔
	The card network or brand (e.g., 'Visa', 'Mastercard', 'Amex'). For all payments other than bank cards, this parameter will be empty.
payment_description	STRING	N/A	N/A	✔
	A masked representation of the card number for security purposes. For all payments other than bank cards, this parameter will shows the payment method name.
expiryMonth	INT	N/A	N/A	✔
	The expiration month of the card (1-12). For all payments other than bank cards, this parameter will not be present.
expiryYear	INT	N/A	N/A	✔
	The expiration year of the card (e.g., 2027). For all payments other than bank cards, this parameter will not be present.
issuerCountry	STRING	N/A	N/A	✔
	The two-letter country code (ISO 3166-1 alpha-2) of the payment method issuer (e.g., 'SA' for Saudi Arabia).
issuerName	STRING	N/A	N/A	✔
	The name of the financial institution that issued the card, or funded the installment plan (for example, 'Valu', 'Arab National Bank', etc)
contact_data	OBJECT			✘
	The main object containing contact transaction details.
	{ "contact_data": { "sessionId": "ZXJtGvFAhtWtKIPgSvmGwmMKKHsfolZFvDKPMETccGUvjvXQLTnDXXXXXXXXXXX", "invoiceNO": "546241", "client": "27610201XXXX", "items": [ { "itemId": "1932", "price": "900.00", "downPayment": "0", "tenor": "24", "adminFees": "0", "isBonus": "false" } ], "price": "900.00", "downPayment": "0" } }
contact_data's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
sessionId	STRING	N/A	N/A	✔
	A unique identifier for the transaction session.
invoiceNo	STRING	N/A	N/A	✔
	The invoice number for tracking the payment plan.
client	STRING	N/A	N/A	✔
	The unique identifier of the client (customer ID).
price	DECIMAL	N/A	N/A	✔
	The total price of all items in the installment plan.
downPayment	DECIMAL	N/A	N/A	✔
	The total down payment amount for all items.
items	Array	N/A	N/A	✔
	A list of items included in the contact transaction.
items's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
itemId	STRING	N/A	N/A	✔
	The unique identifier of the item being purchased.
price	DECIMAL	N/A	N/A	✔
	The total price of the item in the installment plan.
downPayment	DECIMAL	N/A	N/A	✔
	The initial amount paid upfront.
tenor	INT	N/A	N/A	✔
	The number of months (or installments) for repayment.
adminFees	DECIMAL	N/A	N/A	✔
	Any administrative fees associated with the plan.
isBonus	BOOLEAN	N/A	N/A	✔
	Indicates if the item qualifies for a bonus offer.
created_date_from	DATE	Required for search by page for a specific day, created_date_from and created_date_to should be the same date, date format DD/MM/YYYY		✘
	Show invoices resuts in a spicic date.
	{ "profile_id": "47157", "created_date_from": "01/11/2024", "created_date_to": "01/11/2024", "page": 2 }
created_date_to	DATE	Required for search by page for a specific day, created_date_from and created_date_to should be the same date, date format DD/MM/YYYY		✘
	Show invoices resuts in a spicic date.
	{ "profile_id": "47157", "created_date_from": "01/11/2024", "created_date_to": "01/11/2024", "page": 2 }
page	INT	This field is only accepted if the search request is by date range only (so no cart ID/customer ref etc), and the date range is a single day (so from and to date must be the same). The value for page can be between 1 and 20. If no page value is provided, then 1 is assumed.		✘
	Show invoices resuts in a spicic page.
	{ "profile_id": "47157", "created_date_from": "01/11/2024", "created_date_to": "01/11/2024", "page": 2 }
pager	OBJECT			✘
	this object will shows the paging paramters details
	{ "pager": { "page": 2, "pageSize": 500, "pageItems": 500, "totalItems": 1317 } }
pager's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
page	INT	N/A	N/A	✔
	the current page number
pageSize	INT	N/A	N/A	✔
	the max number of items per page
pageItems	INT	N/A	N/A	✔
	the actual number of items on this page
totalItems	INT	N/A	N/A	✔
	the total items available over all pages.

---

Request & Response Payload Samples

Required Parameters Sample Payloads

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.

Sample 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",
    "invoice": {
      "line_items": [
          {
              "unit_cost": 100,
              "quantity":5
          }
      ]
    }
}

Sample Response Payload

{
    "tran_ref": "TST22********159",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "SAR",
    "cart_amount": "500",
    "return": "none",
    "redirect_url": "https://secure.paytabs.com/payment/page/5994585B6B*************B481739688688",
    "invoice": {

       "line_items": [
           {
               "unit_cost": "100",
               "quantity": "5",
  
           }
       ]
   },
    "serviceId": 2,
    "profileId": 9*****4,
    "merchantId": 1*****7,
    "trace": "PMN****4.63****A8.00****C4"
}

Optional Parameters Sample Payloads

The below sample request payload will show you how you can pass the above-mentioned optional 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.

Sample 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": 500,
   "cart_currency": "SAR",
   "paypage_lang": "en",
   "return":"** Valid Return URL **",
   "callback":"** Valid callback URL **",
   "customer_details": {
       "name": "FirstName LastName",
       "email": "[email protected]",
       "phone": "0522222222",
       "street1": "address street",
       "city": "cc",
       "state": "C",
       "country": "AE",
       "zip": "12345"
   },
   "shipping_details": {
       "name": "FirstName LastName",
       "email": "[email protected]",
       "phone": "971555555555",
       "street1": "street2",
       "city": "dubai",
       "state": "dubai",
       "country": "AE",
       "zip": "54321"
   },
   "invoice": {
       "id": 3128281,
       "shipping_charges": "0",
       "extra_charges": "0",
       "extra_discount": "0",
       "total": "500",
       "activation_date": 0,
       "expiry_date": 0,
       "due_date": 0,
       "issue_date": 1733496740,
       "line_items": [
           {
               "unit_cost": "100",
               "quantity": "5",
               "net_total": "500",
               "discount_rate": "0",
               "discount_amount": "0",
               "tax_rate": "0",
               "tax_total": "0",
               "total": "500"
           }
       ]
       },
   "user_defined": {
       "udf1": "UDF1 Test",
       "udf2": "UDF2 Test",
       "udf3": "UDF3 Test",
       "udf4": "UDF4 Test",
       "udf5": "UDF5 Test",
       "udf6": "UDF6 Test",
       "udf7": "UDF7 Test",
       "udf8": "UDF8 Test",
       "udf9": "UDF9 Test"
   },
}

Sample Response Payload

{
    "tran_ref": "TST22********159",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "SAR",
    "cart_amount": "500.00",
    "return":"** Valid Return URL **",
    "callback":"** Valid callback URL **",
    "redirect_url": "https://secure.paytabs.com/payment/page/599455B6B************B4817FD44688",
    "invoice": {
       "id": 3128281,
       "shipping_charges": "0",
       "extra_charges": "0",
       "extra_discount": "0",
       "total": "500",
       "activation_date": 0,
       "expiry_date": 0,
       "due_date": 0,
       "issue_date": 1733496740,
       "line_items": [
           {
               "unit_cost": "500",
               "quantity": "5",
               "net_total": "500",
               "discount_rate": "0",
               "discount_amount": "0",
               "tax_rate": "0",
               "tax_total": "0",
               "total": "500"
           }
       ]
   },
   "customer_details": {
       "name": "FirstName LastName",
       "email": "[email protected]",
       "phone": "0522222222",
       "street1": "address street",
       "city": "cc",
       "state": "C",
       "country": "AE",
       "zip": "12345"
   },
   "shipping_details": {
       "name": "FirstName LastName",
       "email": "[email protected]",
       "phone": "971555555555",
       "street1": "street2",
       "city": "dubai",
       "state": "dubai",
       "country": "AE",
       "zip": "54321"
   },
   "user_defined": {
       "test": "UDF1 Test",
       "test2": "UDF2 Test",
       "udf3": "UDF3 Test",
       "udf4": "UDF4 Test",
       "udf5": "UDF5 Test",
       "udf6": "UDF6 Test",
       "udf7": "UDF7 Test",
       "udf8": "UDF8 Test",
       "udf9": "UDF9 Test"
   },
    "serviceId": 2,
    "profileId": 9*****4,
    "merchantId": 1*****7,
    "trace": "PMN****4.63****A8.00****C4"
}

---

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:

   

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.