PunchOut: Standard JSON payload for session request – TradeCentric

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)

Request field details

JSON root
Params
Custom

Response payload (to TradeCentric)

Response field details

Success response
Error response

Request payload (from TradeCentric)

The code block below shows an example session request payload in our standard JSON format:

JSON

HTTP POST

Session request

{
  "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

Example

{
  "pos": "ABCD1234efg567",
  "operation": "create",
  "return_url": "https://connect.tradecentric.com/gateway/link/api/id/ABCD1234efg567",
  "params": {
    ...
  }
}

Root request field breakdown

pos

Session identifier

Type: String

Provides the unique identifier for the punchout session

Example: "ABCD1234efg567"
operation

Requested action

Values: create, edit, inspect

Specifies whether to create a new session, or to edit or inspect an existing one

Example: "create"
return_url

Return URL

Format: protocol://domain/path

Provides the full TradeCentric URL, including the unique session identifier, that your eCommerce platform should send the return cart to

Example: "https://connect.tradecentric.com/gateway/link/api/id/ABCD1234efg567"
params

Payload details

Groups the punchout session details, which are described in the Params section below

Example: "params": { ... }

Params

Provides the punchout session details, which are described in the subsections below

Metadata

Provides general information about the request

Example

"params": {
  "header": {},
  "type": "setuprequest",
  "mode": "production"
}

Metadata field breakdown

header

Header object

Provides header values

Example: {} = blank
type

Request type

Type: String

Specifies that the request is a setup request

Will be "setuprequest"
mode

Environment mode

Values: production, test

Specifies the environment mode

Example: "production"

Body

Provides contact, return cart, and shipping details for the punchout session

Example

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

Body field breakdown

data

Additional request data

Groups additional attributes, such as user identifiers or other values that your integration may require

Example: "data": {}
contact
Contact object

Identifies the user punching out
- email Email address
  
  Type: String
  
  Provides the user's email address
  
  Example: "contact@buyer.com"
- name Name
  
  Type: String
  
  Provides the user's name
  
  Example: "Contact Name"
- unique Identifier
  
  Type: String
  
  Provides a unique identifier for the user
  
  Example: "contact.name"
buyercookie

Buyer session identifier

Type: String

Provides the session identifier that the buyer generated, which we’ll also include in the PunchOutOrderMessage payload sent to the buyer

Example: "SESSION-123456"
postform

TradeCentric return URL

Type: String

Provides the full URL that our platform will return the cart to

Example: "https://s1-2.ariba.com/Buyer/punchout?..."

Note: You can ignore this field. The return cart payload should use the return_URL, not this URL.
shipping
Shipping object

Provides a shipping address for the session
- data Address data object
  
  Provides the full shipping address
  - address_name Address name
    
    Type: String
    
    Provides the address name
    
    Example: "Main Office"
  - shipping_id Identifier
    
    Type: String
    
    Provides the address identifier
    
    Example: "Main"
  - shipping_business Business name
    
    Type: String
    
    Provides the organization name
    
    Example: "Test Corp."
  - shipping_to Delivery contact name
    
    Type: String
    
    Provides the name of the delivery contact
    
    Example: "Contact Name"
  - shipping_street Street address
    
    Type: String
    
    Provides the street address
    
    Example: "3445 Seminole Trail #218"
  - shipping_city City
    
    Type: String
    
    Provides the city
    
    Example: "Charlottesville"
  - shipping_state Region code
    
    Type: String
    
    Provides the state, province, or region
    
    Example: "VA"
  - shipping_zip Postal code
    
    Type: String
    
    Provides the postal code
    
    Example: "22911"
  - shipping_country Country
    
    Type: String
    
    Provides the country name
    
    Example: "United States"
  - country_id Country code
    
    Format: ISO 3166
    
    Provides the country code
    
    Example: "US"

items

Selected items

Provides details about cart items if the buyer requested to rebuild a cart or retrieve an existing one

Note: Only rebuild or retrieve this cart if the operation field specifies edit or inspect.

primaryId Part identifier

Type: String

Provides the item identifier, such as a part number or Stock Keeping Unit (SKU)

Example: "45L017"
secondaryId Auxiliary part identifier

Type: String

Provides a unique, additional item identifier, such as to indicate a specific color or packaging option

Example: "CART12-ITEM123"
quantity Quantity

Type: Number

Provides the requested quantity

Example: 3
type Item type

Values: in, out

Indicates whether the user should be taken to the item's product page or the item should be added to the user's cart

Example: "in" = user taken to product page, "out" = item added to cart

Note: If the operation field specifies edit, the out value indicates that your organization should rebuild the cart with the item.

Custom

Provides additional custom data about the user or organization punching out, such as identifiers or other values that your integration may require

Example

"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:

JSON

HTTP response

Session request response

{
  "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

ConditionalMax use: 1

Provides the unique URL needed to authenticate the user and start the punchout session

Example

{
  "start_url": "https://www.mystorefront.com/?token=98765ZYXW4321vuts"
}

Success response field breakdown

start_url

Session start URL

Required Format: protocol://domain/path

Provides a tokenized version of the full start URL needed to identify the punchout session and redirect the user to your storefront

Example: "https://www.mystorefront.com/?token=98765ZYXW4321vuts"

Error response

ConditionalMax use: 1

Provides the URL and message for the error page

Example

{
  "start_url": "https://www.mystorefront.com/error?token=98765ZYXW4321vuts&error_type=punchout_authentication_failure",
  "message": "Unable to authenticate the user"
}

Error response field breakdown

start_url

Error URL

Required Format: protocol://domain/path

Provides the full URL, which should include the session start URL, needed to take the user to an error page

Example: "https://www.mystorefront.com/error?token=98765ZYXW4321vuts&error_type=punchout_authentication_failure"
message

Message

Optional Type: String

Provides a message that can help TradeCentric's support team or your support team troubleshoot the request

Example: "Unable to authenticate the user"

Request payload (from TradeCentric)

Request field details

JSON root

Session identifier

Requested action

Return URL

Payload details

Params

Metadata

Header object

Request type

Environment mode

Body

Additional request data

Contact object

Buyer session identifier

TradeCentric return URL

Shipping object

Selected items

Custom

Response payload (to TradeCentric)

Response field details

Success response

Session start URL

Error response

Error URL

Message

Related articles