Request/Response: Cart Currency (cart_currency)
The cart_currency is one of the required parameters that you must use while initiating a hosted payment page. It specifies the currency in which the customer is charged, ensuring the transaction is processed in the correct currency format.​
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_currency | |||
|---|---|---|---|---|
| Description | Indicates the transaction currency, which the customer will be charged with. To know more about this parameter please click here. | |||
| Data Type | STRING | |||
| Required | ✔ | |||
| Min | 1 | |||
| Max | 128 | |||
| Validation Rules | Valid string from the following list: SAR AED BHD EGP EUR GBP HKD IDR INR IQD JOD JPY KWD MAD OMR PKR QAR USD Accepts both upper- and lower-case characters | |||
| 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_currency" 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_currency" 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_currency" 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_currency" 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_currency" 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.