Request/Response: shipping Details (shipping_details)
The shipping_details is one of the optional parameters that you can use while initiating a payment request It allows merchants to prefill the payment page with shipping information, enhancing the user experience by reducing the amount of data entry required at checkout.
Why You Should Use This Parameter​
This is one of the optional parameter that you can use in the Hosted Payment Page and Invoices integration types so that your shipping does not have to fill it himself. Additionally, this object is required to passed in both Own Form and Managed Form integration types.
Parameter Specifications​
| Parameter | | |||
|---|---|---|---|---|
| Description | Indicates the customer shipping details for this payment. If provided, the payment page will be prefilled with the provided data.. | |||
| Data Type | Object | |||
| Required | ✘ | |||
| Sample | | |||
| Nested Parameter | Data Type | Min | Max | Required |
| STRING | 3 | 128 | ✔ |
| STRING | N/A | N/A | ✔ |
| STRING | N/A | N/A | ✔ |
| STRING | 3 | 128 | ✔ |
| STRING | 3 | 128 | ✔ |
| STRING | 2 | 2 | ✔ |
| STRING | N/A | N/A | ✔ |
| STRING | N/A | N/A | ✔ |
Sample Request & Response Payloads​
- Hosted Payment Page
- Invoices
- Managed Form
- Own Form
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",
"shipping_details": {
"name": "first last",
"email": "[email protected]",
"phone": "+966 000000",
"street1": "address street",
"city": "ryad",
"state": "rd",
"country": "SA",
"zip": "12345"
}
}
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.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
"serviceId": 2,
"profileId": 987###,
"merchantId": 1*****7,
"trace": "PMN****4.63****A8.00****C4"
}
As clarified in the Invoices Manual, our Invoices can be initiated through two endpoints, find below the different Payloads for each endpoint
Click to view the full Request Payload for both endpoints
{
"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",
"shipping_details": {
"name": "first last",
"email": "[email protected]",
"phone": "+966 000000",
"street1": "address street",
"city": "ryad",
"state": "rd",
"country": "SA",
"zip": "12345"
},
"invoice": {
"line_items": [
{
"unit_cost": 100,
"quantity":5,
}
]
}
}
Click to view the full Response Payload via Invoice Endpoint
{
"invoice_id": 2072841,
"invoice_link": "https://secure.paytabs.com/payment/request/invoice/2072841/A8CB6A4667A444E79E868206DB76382A"
}
Click to view the full Response Payload via the Payment Endpoint
{
"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.com/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",
"shipping_details": {
"name": "Demo Account",
"email": "[email protected]",
"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.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
"shipping_details": {
"name": "Demo Account",
"email": "[email protected]",
"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",
"shipping_details": {
"name": "Demo Account",
"email": "[email protected]",
"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",
"shipping_details": {
"name": "Demo Account",
"email": "[email protected]",
"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.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
"shipping_details": {
"name": "Demo Account",
"email": "[email protected]",
"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",
"shipping_details": {
"name": "Demo Account",
"email": "[email protected]",
"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"
}
Expected behavior​
- Hosted Payment Page
- Invoices
- Managed Form
- Own Form
-
You will initiate a payment request using the guide mentioned here
-
You will use the "shipping_details" 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 shipping to this URL so the payment process can be finalized, and the shipping will not be required to fill his shipping details as shown below:
-
You will initiate a payment request using the guide mentioned here
-
You will use the "shipping_details" 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 shipping to this URL so the payment process can be finalized, and the shipping will not be required to fill his shipping details as shown below:
-
You will initiate a payment request using the guide mentioned here
-
You will use the "shipping_details" 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 "shipping_details" 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.