Request/Response: Cart Amount (cart_amount)
The cart_amount is one of the required parameters that you must use while initiating a hosted payment page. It defines the total amount of the transaction. It is subject to the merchant’s transaction limits and ensures the customer is charged the correct amount.
Why You Should Use This Parameter
This is one of the required parameters used to validate your API requests to PayTabs, not using this parameter correctly will result in your payment being rejected due to not having this currency enabled in your profile or initiated with a transaction that you do not want
Parameter Specifications
| Parameter | cart_amount | |||
|---|---|---|---|---|
| Description | 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. | |||
| Data Type | DECIMAL | |||
| Required | ✔ | |||
| Min | 0.01 | |||
| Max | 9999999999.99 | |||
| Sample | | |||
Sample Request & Response Payloads
- Hosted Payment Page
- Invoices
- Managed Form
- Own Form
- PayLinks
Click to view the full 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",
}
Click to view the full 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": "none",
"redirect_url": "https://secure.paytabs.sa/payment/page/599458B182E5B6B********************B4817FD44318539688688",
"serviceId": 2,
"profileId": 987###,
"merchantId": 1*****7,
"trace": "PMN****4.63****A8.00****C4"
}
Click to view the full 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",
}
Click to view the full 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": "none",
"redirect_url": "https://secure.paytabs.sa/payment/page/599458B182E5B6B********************B4817FD44318539688688",
"serviceId": 2,
"profileId": 987###,
"merchantId": 1*****7,
"trace": "PMN****4.63****A8.00****C4"
}
Click to view the full 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",
"customer_details": {
"name": "Demo Account",
"email": "demo@PayTabs.com",
"phone": "+966 0000000000",
"street1": "address street",
"city": "city",
"state": "state",
"country": "SA",
"zip": "45555",
"ip": "1.1.1.1"
},
"payment_token": "xxxxxxxxxxxx"
}
Click to view the full Response Payload via 3DS cards !
{
"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": "none",
"redirect_url": "https://secure.paytabs.sa/payment/page/599458B182E5B6B********************B4817FD44318539688688",
"customer_details": {
"name": "Demo Account",
"email": "demo@PayTabs.com",
"phone": "+966 0000000000",
"street1": "address street",
"city": "city",
"state": "state",
"country": "SA",
"zip": "45555",
"ip": "1.1.1.1"
},
"payment_info": {
"payment_method": "Visa",
"card_type": "Credit",
"card_scheme": "Visa",
"payment_description": "4111 11## #### 1111",
"expiryMonth": 12,
"expiryYear": 2022
},
"serviceId": 8,
"serviceId": 2,
"profileId": 987###,
"merchantId": 1*****7,
"trace": "PMN****4.63****A8.00****C4"
}
Click to view the full Response Payload via Non 3DS cards !
{
"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",
"tran_currency": "SAR",
"tran_total": "500.00",
"return": "none",
"customer_details": {
"name": "Demo Account",
"email": "demo@PayTabs.com",
"phone": "+966 0000000000",
"street1": "address street",
"city": "city",
"state": "state",
"country": "SA",
"zip": "45555",
"ip": "1.1.1.1"
},
"payment_result": {
"response_status": "A",
"response_code": "G17534",
"response_message": "Authorised",
"transaction_time": "2022-11-30T14:12:14Z"
},
"payment_info": {
"payment_method": "Visa",
"card_type": "Credit",
"card_scheme": "Visa",
"payment_description": "4111 11## #### 1111",
"expiryMonth": 12,
"expiryYear": 2023
},
"serviceId": 8,
"serviceId": 2,
"profileId": 987###,
"merchantId": 1*****7,
"trace": "PMN****4.63****A8.00****C4"
}
Click to view the full 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",
"customer_details": {
"name": "Demo Account",
"email": "demo@PayTabs.com",
"phone": "+966 0000000000",
"street1": "address street",
"city": "city",
"state": "state",
"country": "SA",
"zip": "45555",
"ip": "1.1.1.1"
},
"card_details": {
"pan": "4111111111111111",
"cvv": "123",
"expiry_month": 12,
"expiry_year": 2023
}
}
Click to view the full Response Payload via 3DS cards !
{
"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": "none",
"redirect_url": "https://secure.paytabs.sa/payment/page/599458B182E5B6B********************B4817FD44318539688688",
"customer_details": {
"name": "Demo Account",
"email": "demo@PayTabs.com",
"phone": "+966 0000000000",
"street1": "address street",
"city": "city",
"state": "state",
"country": "SA",
"zip": "45555",
"ip": "1.1.1.1"
},
"payment_info": {
"payment_method": "Visa",
"card_type": "Credit",
"card_scheme": "Visa",
"payment_description": "4111 11## #### 1111",
"expiryMonth": 12,
"expiryYear": 2022
},
"serviceId": 8,
"serviceId": 2,
"profileId": 987###,
"merchantId": 1*****7,
"trace": "PMN****4.63****A8.00****C4"
}
Click to view the full Response Payload via Non 3DS cards !
{
"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",
"tran_currency": "SAR",
"tran_total": "500.00",
"return": "none",
"customer_details": {
"name": "Demo Account",
"email": "demo@PayTabs.com",
"phone": "+966 0000000000",
"street1": "address street",
"city": "city",
"state": "state",
"country": "SA",
"zip": "45555",
"ip": "1.1.1.1"
},
"payment_result": {
"response_status": "A",
"response_code": "G17534",
"response_message": "Authorised",
"transaction_time": "2022-11-30T14:12:14Z"
},
"payment_info": {
"payment_method": "Visa",
"card_type": "Credit",
"card_scheme": "Visa",
"payment_description": "4111 11## #### 1111",
"expiryMonth": 12,
"expiryYear": 2023
},
"serviceId": 8,
"serviceId": 2,
"profileId": 987###,
"merchantId": 1*****7,
"trace": "PMN****4.63****A8.00****C4"
}
Click to view the full Request Payload!
{
"profile_id": 987###,
"link_title": "AK-Test Title",
"cart_id": "CART#1001",
"cart_description": "Description of the items/services",
"cart_currency": "SAR",
"cart_amount": "500",
"cart_min": "0",
"cart_max": "0",
"shipping_required": false,
"donation_mode": false,
}
Click to view the full Response Payload!
{
"link_id": 72160,
"profile_id": 987###,
"link_url": "https://secure.paytabs.sa/payment/link/47161/721551",
"link_title": "AK-Test Title",
"cart_id": "CART#1001",
"cart_description": "Description of the items/services",
"cart_currency": "SAR",
"cart_amount": "500",
"cart_min": "0",
"cart_max": "0",
"shipping_required": false,
"link_status": true,
"donation_mode": false,
}
Expected behavior
- Hosted Payment Page
- Invoices
- Managed Form
- Own Form
- PayLinks
-
You will initiate a payment request using the guide mentioned here
-
You will use the "cart_amount" parameter according to the above Specifications
-
Then you will receive the response payload containing the "redirect_url" meaning you have initiated a correct payment request.
-
Finally, you should redirect your customer to this URL so the payment process can be finalized.
-
You will initiate a payment request using the guide mentioned here
-
You will use the "cart_amount" parameter according to the above Specifications
-
Then you will receive the response payload containing the "redirect_url" or "invoice_url" meaning you have initiated a correct Invoice payment request.
-
Finally, you should redirect your customer to this URL so the payment process can be finalized.
-
You will initiate a payment request using the guide mentioned here
-
You will use the "cart_amount" parameter according to the above Specifications
-
As you are using the managed form, then the next step will be authenticating and finalizing the payment directly. Finally, you will receive the transaction response that contains the payment_result object where you can use it to identify if the payment was successful or not.
-
You will initiate a payment request using the guide mentioned here
-
You will use the "cart_amount" parameter according to the above Specifications
-
As you are using your own form, then the next will be authenticating and finalizing the payment directly. Finally, you will receive the transaction response that contains the payment_result object where you can use it to identify if the payment was successful or not.
-
You will initiate a payment request using the guide mentioned in our PayLinks Manual
-
You will use the "cart_amount" parameter according to the above Specifications
-
Then you will receive the response payload containing the "link_url" meaning you have initiated a correct PayLink payment request.s
-
Finally, you should redirect your customer to this URL so the payment process can be finalized.