How to integrate receipts from SAP Customer Checkout manager

This blog post explains how receipts that reach SAP Customer Checkout manager can be forwarded to your external system and what fields are relevant for processing. This allows you to build an integration and use all information that are provided in the receipt to full extent.

SAP Customer Checkout manager offers a generic interface for receipts while it also offers dedicated interfaces for SAP S/4HANA Retail via WPUBON/WPUFIB and for SAP S/4HANA Cloud via SOAP calls (Sales transaction and Financial transaction). If you do not use SAP S/4HANA Retail and want to receive receipts that your PoS instances send to SAP Customer Checkout manager, this blog post is of your interest.

The receipts are sent one by one to the external system immediately once they reach the SAP Customer Checkout manager. As of FP12 of SAP Customer Checkout, a consolidation of receipts is not offered. If a constant and immediate forwarding is too much for your use case, the receipt export offers a way to get the receipts zipped in one file or exported to an SFTP destination of your choice. Be it the immediate forwarding or the receipt export, the format of the receipts that you receive is the same and shall be explained in the following so that you can leverage the most out of the data.

In the following, we first set up our external system in SAP Customer Checkout for receipt forwarding, visit then the places to check if the forwarding worked successfully, and finally do a deep dive on the receipt payload and what fields are relevant. If you plan to use the receipt export functionality, you can directly jump to the second section.

Instant receipt forwarding

The instant receipt forwarding allows to define a communication system with a destination to send the receipts received from a SAP Customer Checkout POS of the types “Cash in”, “Cash out”, “Pay in”, “Pay out” and “Sales receipts” in real time in JSON format, to a destination service that is ready to accept the message and map it to the desired backend system of the vendor.

Communication systems

On the SAP CCO manager launchpad, open the Communication system tile.

Click on the “+” button to create a communication system.

Enter details to create the communication system.

Communication system details

Navigate to the destinations tab.

Click on Add to create a destination.

Enter destination details

Destination details

In case of HTTPS, please enter in the “Host” field a path such as “https://localhost”. If you use the standard ports, enter “80” for HTTP and “443” for HTTPS. The path field represents the base path of the destination.

Example:

If your external system provides two endpoints, one for receipts, one for stock overview calls, the endpoint addresses could look as follows:

http://localhost:3000/api/receipt

http://localhost:3000/api/stockoverview

In this case, the base path to enter in the destination dialog is “/api”. The concrete endpoint for the service will be composed later. If your external system also provides an endpoint for ping calls, such as

http://localhost:3000/api/ping

you can add the “/ping” endpoint in the ping field. This field can also be left empty. The standard authentication method that SAP Customer Checkout manager uses for external calls is “Basic auth”. For that, please enter a valid username and password of the external system.

Check the connection.

Communication arrangements

After successfully maintaining the destination, we can configure the concrete endpoint to receive receipt data. For that, we create a communication arrangement. Move back to the SAP Customer Checkout manager launchpad by clicking on the SAP logo in the top left corner.

On SAP CCO manager launchpad, open the Communication arrangement tile.

Click on the “+” button to create a communication arrangement.

Select the communication system that was created before and click on Save.

Navigate to the tab Outbound services

Select the outbound service “Receipt”

Edit the “Receipt” outbound service configuration.

Enter the receipt endpoint path and change the status to “Active”.

At the top of the page, one can find the resulting endpoint address that is used for the outbound service. The HTTP method that is used for the outbound call is POST.

Optional: Configure the generic receipt outbound service

On the tab “Configuration” of the outbound service, several options are offered.

The endpoint is now configured in SAP Customer Checkout manager to receive receipts once they are sent to the CCO manager.

For middleware software that operates on XSD schema declarations to create the required objects to setup the endpoint such as SAP PI/PO, please use the XSD files attached to the SAP Note 2951593.

With that the receipt endpoint is finally configured. As a next step, let’s post some receipts to the endpoint.

Dispatched receipts

In the receipt app of the CCO manager, the state of dispatching can be seen for each receipt.

Open the Receipt tile.

Select a receipt from the list.

Navigate to the tab “Dispatch states”.

Per active receipt outbound service, you can find an entry in the list distinguished by the name of the communication system. In case of an unsuccessful dispatch operation, you can click on the paper plane symbol to resend the receipt to the communication system. If several communication systems are configured and any of them failed, the action button “Dispatch all failed postings” below reinitiates the posting of the receipt.

Receipt reposting job

The posting of receipts can fail, e.g., because of wrong configuration or when the destination is not reachable. To ensure that all receipts reach the destination, a job can be configured to repost once or regularly receipts to the destination.

Open the Jobs tile

Click on the “+” button

Select the job type “Receipt: Repost”.

Configure the job to repost receipts.

Receipt reposting job details

Please note that a job covers only one communication system. Hence, per communication system one job has to be configured.

Receipt export

Besides the instant forwarding of receipts, CCO manager allows as well to export receipts by selection criteria regularly or once. The receipts are still handled one by one and are not consolidated. The receipts can be exported to a file to download as well as exported to a communication system. In the following, the one-time export of receipts via the app “Receipt export” is described, then how to configure the receipt export as a job.

Open the tile “Receipt export”

Configure the receipt export settings.

Receipt export details

After the selection criteria are set, click on “Execute” to initiate the export. An entry can be seen in the “History” section of the app. In the background the data is collected. While the collection is in progress, the status of the operation is “Running”. Once done, the status changes to “Finished”.

To download the receipt export result, click on the download button in the History section.

Configure SFTP destination for the receipt export

To export receipts on a regular basis, an SFTP destination shall be configured.

1. Open the tile “Communication systems”, select the respective communication system, and navigate to the tab “Destinations”. Click on the “Add” button.
   
2. Select the destination type “SFTP”

SFTP destination job details

To test the connection to the SFTP destination, select the “Check connection” button as described above.

Receipt export job

To export receipts regularly, a job has to be configured in the Jobs app.

1. Open the Jobs tile
   
2. Select the type “Receipt: Export”
   
3. Configure the job with the fields as described above

Format of forwarded receipts and JSON receipt export

Receipts are sent to external systems formatted as JSON (JavaScript Object Notation). The receipt has a hierarchical data structure. The JSON format offers the most detailed information on each receipt for any integration scenario. Other data formats are not supported for the “Generic” communication scenario. In the following, the most relevant structures and fields shall be explained.

The receipt export format

The payload comprises three fields on header level:

{
    "checkoutPrefix": "A001",
    "receipt": {
        ...
    },
    "customer": null
}

The field “checkoutPrefix” represents the prefix of the cash desk that sent the receipt. The field “customer” contains the customer data that is assigned to the given receipt. If no customer is assigned, “null” is stated. In the following, the receipt data structure is described in detail.

Difference between receipt forwarding and receipt export format

The format of the payload differs slightly between the receipt forwarding and the receipt export format. While the main content per receipt follows the same data structure, the comprising structure differs. On the left, the structure of the receipt export is depicted. The receipts are listed in an array. On the right, the receipt forwarding payload structure is depicted. It represents only one receipt.

Receipt data structure

Following diagram describes how the receipt data is structured.

The receipt has header data, sales items, tax items, payment items, charge elements, reference to its cash desk closing if assigned, coupon data with application amounts and other meta data such as print logo, calculation meta data, cash desk print receipt information that can be used for receipt printing or receipt recalculation.

This document explains the most relevant fields of the header data, sales, tax, and payment items, charge elements and coupon data for further processing.

Receipt header

The receipt header contains several relevant information, such as the cash desk prefix, the receipt ID, business transaction date, various amounts, and the cashier that created the receipt. In the following we describe the most important fields.

The referencing fields are:

Tax items

The fields of the tax item are:

Sales items

The fields of the sales item are:

Payment items

The fields of the payment item are:

Charge elements

The fields of the charge element are:

Cash desk closing

The fields of the cash desk closing are:

Coupon assignments

The fields of the coupon assignment are: