Do you operate your e-commerce platform as an in-house development? This document will help you implement the necessary interfaces to our PunchOut gateway.
You initially create and subsequently update customers via the PunchCommerce web interface. The following parameters are maintained by the supplier for each customer:
Entry address
URL of the online shop to which the customer is redirected after successful authentication
Customer ID (uID)
Value that is passed to the entry address to identify the customer
Calling up your online shop
After the customer has been successfully authenticated on our gateway, the customer is redirected to the entry address defined in the customer configuration.
PunchCommerce currently supports the "classic" PunchOut and the PunchOut in an iFrame within the calling e-procurement or ERP system and the PunchOut in a separate browser window.
The entry address is extended by the parameters sID (session identifier) and uID (customer identifier), so that the final URL is structured according to the following scheme:
https://{hostname}.{domain}.{tld}/punchcommerce/authenticate?sID={UUID}&uID= {customer.identifier}
It must be ensured that all headers that prevent embedding as an iFrame and access to cookies from the main frame during the PunchOut session are temporarily removed when the user is logged in.
The user in your system must be extended so that the uID can be maintained for the customer. The sID is generated by us for each PunchOut session and corresponds to a UUID.
Since this is typically a service user and several people use the same service user as part of the PunchOut, it must be ensured that different shopping carts can be used in parallel in different sessions of the same service user.
The shopping cart must be empty at the start of a PunchOut session.
General requirements during the PunchOut session
- During the PunchOut session, the SameSite attribute must be set to the value none and the Secure attribute must be set to 1 for all cookies relevant to the session
- The X-Frame-Options header must be removed during the PunchOut session if it is present
- The checkout is replaced by the overview of the shopping cart for the PunchOut and the forwarding to PunchCommerce
- The label of the relevant user actions "Checkout" is replaced accordingly by a label "PunchOut" or "Back to the e-procurement system"
Returning the shopping cart
After the customer has finally filled their shopping cart, the shopping cart must be sent back to our gateway as a JSON object together with the session identifier (sID). Surcharges or discounts are passed to our gateway as a separate shopping cart item - this also applies to shipping costs.
{
"basket":[
{
"product_ordernumber": "23762", "product_name": "Parchment paper", "quantity": 1,
"item_price": 2.623,
"price": 2.623,
"price_net": 2.2042016806723, "tax_rate": 19,
"product": {
"id": "21312432343",
"ordernumber": "23762",
"brand": "Netzdirektion",
"brand_ordernumber": "67906",
"title": "Parchment paper",
"category": "Test category",
"description": "1/8 sheet white",
"description_long": "67906 Parchment paper 1/8 sheet white", "image_url": "",
"price": 2.623,
"tax_rate": 19,
"purchase_unit": 12.5, "reference_unit": 1,
"unit": "kg",
"unit_name": "kg", "packaging_unit": "Karton", "weight": 0,
"shipping_time": 8,
"classification_type": "ECLASS",
"classification": "90909090",
"custom_field1": "0.19",
"custom_field2": "BX",
...
"custom_field10": null
}
]
}
Here an http POST request is to be executed to the following address. The request body should contain the shopping cart in the same way as the following structure.
https://www.punchcommerce.de/gateway/v3/return?sID={UUID}
PunchCommerce applies the field mapping defined for the customer to the shopping cart and transmits the shopping cart to the calling e-procurement system via the respective PunchOut protocol. Details can be found in the current Swagger documentation.
Links
