The session request payload requests a punchout session to your eCommerce platform. For standard integrations that receive JSON payloads, the TradeCentric platform transforms the buyer's session request into our standard JSON format. Then, our platform delivers the payload to your endpoint.
For punchout sessions to start successfully, your eCommerce platform must accept our standard JSON format and respond with a start URL. This article describes the standard JSON request and response formats.
Jump to:
Request payload (from TradeCentric)
The code block below shows an example session request payload in our standard JSON format:
{
"pos": "ABCD1234efg567",
"operation": "create",
"return_url": "https://connect.tradecentric.com/gateway/link/api/id/ABCD1234efg567",
"params": {
"header": {},
"type": "setuprequest",
"mode": "production",
"body": {
"data": {},
"contact": {
"email": "contact@buyer.com",
"name": "Contact Name",
"unique": "contact.name"
},
"buyercookie": "SESSION-123456",
"postform": "https://s1-2.ariba.com/Buyer/punchout?client=HTML.1234567890ABCDEFGHIJ0987654321kl.Node12produs-c7-buyer-s2-z1-3us2gcpint&responseid=9&locale=en_US",
"shipping": {
"data": {
"address_name": "Main Office",
"shipping_id": "Main",
"shipping_business": "Test Corp.",
"shipping_to": "Contact Name",
"shipping_street": "3445 Seminole Trail #218",
"shipping_city": "Charlottesville",
"shipping_state": "VA",
"shipping_zip": "22911",
"shipping_country": "United States",
"country_id": "US"
}
},
"items": [
{
"primaryId": "45L017",
"secondaryId": "CART12-ITEM123",
"quantity": 3,
"type": "out"
}
]
},
"custom": {
"organisation_name": "Buyer Corp.",
"organisation_id": "123"
}
}
}
Request field details
A standard JSON session request payload has a root object and a params object, with an optional custom object. The subsections below explain each object and its fields.
JSON root
Applies identifying information to the entire payload
{
"pos": "ABCD1234efg567",
"operation": "create",
"return_url": "https://connect.tradecentric.com/gateway/link/api/id/ABCD1234efg567",
"params": {
...
}
}
Params
Provides the punchout session details, which are described in the subsections below
Metadata
Provides general information about the request
"params": {
"header": {},
"type": "setuprequest",
"mode": "production"
}
Body
Provides contact, return cart, and shipping details for the punchout session
"body": {
"data": {},
"contact": {
"email": "contact@buyer.com",
"name": "Contact Name",
"unique": "contact.name"
},
"buyercookie": "SESSION-123456",
"postform": "https://s1-2.ariba.com/Buyer/punchout?client=HTML.1234567890ABCDEFGHIJ0987654321kl.Node12produs-c7-buyer-s2-z1-3us2gcpint&responseid=9&locale=en_US",
"shipping": {
"data": {
"address_name": "Main Office",
"shipping_id": "Main",
"shipping_business": "Test Corp.",
"shipping_to": "Contact Name",
"shipping_street": "3445 Seminole Trail #218",
"shipping_city": "Charlottesville",
"shipping_state": "VA",
"shipping_zip": "22911",
"shipping_country": "United States",
"country_id": "US"
}
},
"items": [
{
"primaryId": "45L017",
"secondaryId": "CART12-ITEM123",
"quantity": 3,
"type": "out"
}
]
}
Custom
Provides additional custom data about the user or organization punching out, such as identifiers or other values that your integration may require
"custom": {
"organisation_name": "Buyer Corp.",
"organisation_id": "123"
}
Response payload (to TradeCentric)
Once your eCommerce platform processes the session request, it should return a JSON response body. This response body should provide either a URL to start the punchout session or information about an error page.
The code block below shows an example session request payload in our standard JSON format:
{
"start_url": "https://www.mystorefront.com/?token=98765ZYXW4321vuts"
}
Response field details
The subsections below explain the fields of a success response and an error response.
Success response
Provides the unique URL needed to authenticate the user and start the punchout session
{
"start_url": "https://www.mystorefront.com/?token=98765ZYXW4321vuts"
}
Error response
Provides the URL and message for the error page
{
"start_url": "https://www.mystorefront.com/error?token=98765ZYXW4321vuts&error_type=punchout_authentication_failure",
"message": "Unable to authenticate the user"
}