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.

 

The Communication systems app

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

 

Add communication system

Enter details to create the communication system.

 

Enter communication system parameters

Communication system details

Communication scenario	Choose “Generic” (CCOm offers communication scenarios as well for SAP S/4HANA, SAP Customer Checkout manager)
Name	Name of the communication system
Status	Active, Inactive, or Draft. Choose “Active”.

Navigate to the destinations tab.

 

Tab Destinations

Click on Add to create a destination.

 

Add button for destinations

Enter destination details

 

Destination parameters

Destination details

Type	HTTP, Communication takes place using HTTP/HTTPS
Name	The name of the destination
Description	Description of the destination
Host	Host address of the destination
Port	The port of the destination
Path	The base path for all endpoints of the destination
User name	Username of the technical user that is used to connect to the destination
Password	Password of the technical user that is used to connect to the destination
Ping Path	(Optional) The endpoint path for executing a ping call to check the availability of the server
Timeout	In seconds. Max. period of a call to the destination till it times out
Status	Specifies whether this destination is active or inactive

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.

 

Ping the destination

 

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.

 

The communication arrangements app

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

 

Add a communication arrangement

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

 

Select your communication system

Navigate to the tab Outbound services

 

Outbound services tab

Select the outbound service “Receipt”

 

Outbound services of Generic

Edit the “Receipt” outbound service configuration.

 

Edit outbound service

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

 

Active configured receipt endpoint

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

 

The generic receipt outbound service configuration options

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

Resolve sales sets	Flag if sales sets in receipts shall be resolved to their sub items directly attached to the receipt
Send valid sales items only	Flag if all sales items (also voided items) or only the valid ones shall be transmitted
Send valid payment items only	Flag if all payment items (also voided items) or only valid ones shall be transmitted
Aggregate coupon assignments	Not relevant

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.

 

The receipt app

Select a receipt from the list.

 

List of receipts

Navigate to the tab “Dispatch states”.

 

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

 

The Jobs app

Click on the “+” button

 

Add a new job

Select the job type “Receipt: Repost”.

 

Select the Receipt repost job type

Configure the job to repost receipts.

 

Set parameters for receipt reposting

Receipt reposting job details

Description	Optional
Type	Choose between “Immediate” (one time execution), “Single” (one time execution), “Hourly”, “Daily”, “Weekly”, “Monthly”, or “Cron expression” and configure accordingly
Start reposting from (based on business transaction date)	Optional. The date from which onwards all receipts are resent
Communication system	Communication system that supports receipt posting to which receipts shall be sent
Dispatch status	“Send failed” (all receipts that are in status “failed”) or “Send failed and unposted” (all receipts that are in status “failed” and those for which no entry is made, e.g., after a server crash)

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”

 

The Receipt exports app

Configure the receipt export settings.

 

The parameters of the Receipt export job

Receipt export details

Description	A description of the receipt export action
Format	“EXCEL” (Receipts in a list in Excel format), “IDEA” (Exports for all receipts sales, payment and tax item information, text file format), “JSON” (contains all stored information about each receipt, same format as for the instant forwarding), “PDF (Cash book)”, “PDF (Cash journal)”
File name template	The template of the file name after export
Number of receipts per file	Threshold how many receipts shall be in an exported file, when above a new file is created
Date from	Starting date (optional)
Date to	End date (optional)
Type	Sales transaction, Cash transaction, or empty (means both)
Status	Void, Posted, Open/Parked, empty (means all)
POS group	The POS group on which the export shall be restricted (for all if left empty)
POS system	The POS system on which the export shall be restricted (for all if left empty)

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.

 

The exported receipts

 

Configure SFTP destination for the receipt export

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

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

 

1. 1. Select the destination type “SFTP”

 

 

The SFTP destination creation dialog

SFTP destination job details

Name	Name of the destination
Description	Description for the destination
Host	Host of the SFTP server
Port	SFTP server port
Path	The path on the SFTP server to which files shall be exported
User name	Username for the SFTP server connection
Passphrase	Optional. In case of a username/password login, the password of the user. In case of a certificate-based login, the field can be left empty
Private key file name	The file name of the certificate private key
Private key	The content of the private key to be pasted (use this field or the file name)
Use known hosts file	Flag if the connection should be restricted by the known hosts file
Timeout	Timeout for connection to the SFTP server
Status	Active or Inactive

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. 1. Open the Jobs tile

 

1. 1. Select the type “Receipt: Export”

 

1. 1. 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 data structure overview

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. A detailed description of all fields can be found in the SAP Customer Checkout API documentation (API documentation in SAP Customer Checkout Manager – SAP Help Portal).

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.

Field	Description
businessTransactionDate	The business transaction date of the receipt
cancellationStatus	Indicator if the receipt is cancelled (“1” means not cancelled, “2” partially cancelled, “3” cancelled)
cashDeskClosingID	The cash desk closing ID to which the receipt is assigned
createdAt	The unix timestamp when the receipt was created
createdBy	The cashier that created the receipt
currency	The currency of the receipt
discountablePaymentGrossAmount	The total receipt gross amount to be paid that is discountable (sum of discountable sales items)
discountAmount	In case of a header discount applied on the receipt, the absolute discount amount
discountPercentage	In case of a header discount applied on the receipt, the discount in percent
discountPurposeCode	In case of a header discount on the receipt, the according purpose code
feeGrossAmount	The calculated gross amount of all fees
feeNetAmount	The calculated net amount of all fees
feeTaxAmount	The calculated tax amount of all fees
id	The receipt/invoice ID
notRoundedPaymentGrossAmount	The total gross amount of the receipt before header rounding
paymentGrossAmount	The total receipt gross amount that is to be paid, contains discounts and fees. Use this field for the receipt total in your integration.
paymentGrossAmountWithoutReceiptDiscount	The total gross amount to be paid without the receipt discount
paymentGrossAmountWithoutVoucher	The total gross amount to be paid excluding voucher amounts
paymentNetAmount	The total net amount to the paid
paymentTaxAmount	The tax amount of the receipt to be paid
percentageDiscount	Flag if the header discount was a percentage or absolute
posGroupId	The ID of the POS group to which the cash desk is assigned
posSystemId	The cash desk ID
priceListId	The ID of the price list
receiptID	The ID of the receipt
roundingLevel	The rounding level (“1” means not used, “2” header rounding, “3” item rounding)
roundingUsed	Flag if rounding is applied on the receipt
serviceChargeGrossAmount	The amount of all calculated service charges including tax
serviceChargeNetAmount	The net amount of all calculated service charges
serviceChargeTaxAmount	The calculated tax amount of all service charges
status	The status of receipt (“2” means posted, “6” voided)
totalGrossAmount	The total gross amount based on the sale item unit amount without discounts and fees
totalNetAmount	The total net amount based on the sale item unit amounts without discounts and fees
totalTaxAmount	The total tax amount based on the sale item unit amounts without discounts and fees
typeCode	The type code of the receipt (“1” means sales receipt, “2” cash in receipt, “3” cash out receipt, “5” cash desk closing cash in, “6” cash desk closing cash out, “7” cash desk closing cash balancing, “8” pay in, “9” pay out, “10” cash desk closing carry over, “11” no sale receipt, “12” reserve receipt)

The referencing fields are:

Field	Description
calculationMetaData	The calculation meta data used for receipt recalculation
cashDeskClosing	Reference data on the cash desk closing
cashDeskPrintReceiptInformation	Cash desk configuration data used for receipt printing, such as VAT registration number
chargeElements	The charge elements (comprises fees and service charges)
paymentItems	The payment items of the receipt
printLogo	The logo that was used in the receipt print
salesItems	The sales items of the receipt
taxItems	The tax items

 

 

Tax items

The fields of the tax item are:

Field	Description
businessTransactionAmount	The aggregated tax amount of this tax rate
externalID	The position of the tax item
productTaxationCharacteristicsCode	The product taxation characteristics code
taxCountryCode	The country code of the tax rate
taxRate	The tax rate
taxRateTypeCode	The type code of the tax rate

 

 

Sales items

The fields of the sales item are:

Field	Description
cancellationSalesItem	Indicator if the sales item cancels a previous sales item
courseId	The assigned course (restaurant mode)
customerReturnReasonCode	The return reason code in case of a return
deliveredNow	Relevant if receipt type is “Reserve invoice”. Indicator if the sold quantity is delivered along with the sales
deliveredQuantity	Relevant if receipt type is “Reserve invoice”. The quantity of the sales item that is handed out to the customer
deliveredQuantityManuallyChanged	Indicator, if the delivered quantity was changed by the cashier
description	The description of the sales item
discountable	Indicator if the sales item is discountable
discountAmount	If an item discount is applied, the absolute discount amount
discountAmountFromReceipt	The partial amount of the header discount that is distributed to the sales item
discountPercentage	The percentage of the item discount if applied
discountPurposeCode	If an item discount is applied, the purpose code
discountPurposeCodeFromReceipt	The discount purpose code of the receipt discount that is distributed to this sales item
externalID	The position of the sales item in the sales receipt
feeGrossAmount	The gross amount of the fee that is calculated for the sales item
feeNetAmount	The net amount of the fee that is calculated for the sales item
feeTaxAmount	The tax amount of the fee that is calculated for the sales item
grossAmount	The gross amount of the sales item without discount or rounding
id	If a material sales item, the material code, otherwise e.g. the sales business document id
managedBy	Indicator if the sales item represents a serial or batch number article (“1” means none, “2” serial number, “3” batch number)
managedByNumber	The serial or batch number assigned to the sales item
material > externalID	The article ID
material > materialDescription	The description of the article
material > prodCatID	Material article group
netAmount	Net amount of the sales item without discount or rounding
notRoundedPaymentGrossAmount	The payment gross amount before item rounding
paymentGrossAmount	The calculated gross amount to be paid for the sales item after header and item discounts
paymentGrossAmountWithoutReceiptDiscount	The sales item payment gross amount without the partial distributed receipt discount
paymentNetAmount	The net amount of the sales item to be paid
paymentTaxAmount	The tax amount to be paid for the sales item after discounts
percentageDiscount	Indicator if the applied item discount is based on a percentage or absolute
priceListId	The ID of the price list from which the standard price is taken
productTaxationCharacteristicsCode	The product taxation characteristics code that is assigned to the sales item
quantity	The quantity of the sales item
quantityTypeCode	The unit of measure
quantityTypeCodeName	The name of the unit of measure
serviceChargeGrossAmount	The gross amount of the service charge that is calculated for the sales item
serviceChargeNetAmount	The net amount of the service charge that is calculated for the sales item
serviceChargeTaxAmount	The tax amount of the service charge that is calculated for the sales item
status	The status of the sales item (“2” means confirmed, “3” void, “4” invalid)
stockArea	The warehouse that is assigned to the sales item
taxAmount	The tax amount of the sales item without discount or rounding
taxCountryCode	The country code for the tax rate
taxRate	The tax rate that is applied to the sales item
taxRateTypeCode	The type code of the tax rate assigned to the sales item
taxRateTypeCodeChanged	Indicator if the tax rate type code was manually changed by the cashier
typeCode	The type code of the sales item (“1” means material, “2” voucher, “3” special sales item, “4” cash in/out, “5” cash balancing, “6” invoice, “7” pay in/out, “8” down payment, “9” paid down payment, “10” credit memo, “11” payment on account, “12” sales set, “13” expense”, “14” tip)
unitBaseQuantity	The base quantity of the unit, usually 1.
unitBaseQuantityTypeCode	The unit of measure of the unit base
unitGrossAmount	The gross amount per unit
unitGrossAmountOrigin	The gross amount per unit based on the price list
unitNetAmount	The net amount per unit
unitNetAmountOrigin	The original unit net amount (before any adaptations based on the pricelist)
unitPriceChanged	Indicator if the unit price was manually changed by the cashier
unitTaxAmount	The tax amount of the unit

 

Payment items

The fields of the payment item are:

Field	Description
additionalPaymentReference	Additional transaction reference field for the payment
businessTransactionAmount	The business transaction amount of the payment
businessTransactioncurrency	Business transaction currency
creditCardErpTypeCode	The ERP type code of the credit card out of the CCOm configuration
creditCardId	The credit card ID
creditCardNumber	A dummy credit card number assigned to the payment item
creditCardTypeCode	The credit card type code
creditCardTypeName	The credit card name
exchangeRateUsed	The exchange rate used for payment
externalID	The position of the payment item in the receipt
originalBusinessTransactionAmount	The original business transaction amount, if it deviates in the paid currency
originalBusinessTransactioncurrency	Original business transaction currency, if it deviates in the paid currency
paymentFormCode	The payment form code, “02” means Card payment, “05” back transfer, “06” check, “09” cash, “20” voucher, “30” debtor item
paymentTransactionReferenceID	Transaction reference ID of the payment
pettyCashID	Petty cash ID
roundingAmount	The rounding amount
status	The status of the payment item, “2” means confirmed, “3” cancelled, “5” void
transactionDate	The transaction date and time of the payment

 

Charge elements

The fields of the charge element are:

Field	Description
chargeElementConfigId	The ID of the charge element type
chargeElementConfigName	The name of the charge element type
chargeElementType	The type of the charge element (“FEE” or “SERVICE_CHARGE”)
grossAmount	The gross amount of the charge element
journalAccount	The journal account of the charge element type
netAmount	The net amount of the charge element
productTaxationCharacteristicsCode	The product taxation characteristics code of the tax rate
taxAmount	The tax amount of the charge element
taxCountryCode	The country code of the tax rate
taxRate	The tax rate
taxRateTypeCode	The tax rate type code

 

Cash desk closing

The fields of the cash desk closing are:

Field	Description
cashDeskClosingID	The ID of the cash desk closing
companyId	The company ID if the cash desk closing is assigned to a specific company
currency	The currency code of the cash desk closing
drawerId	The drawer ID if central drawer management is activated

 

Coupon assignments

The fields of the coupon assignment are:

Field	Description
appliedOnReceiptLevel	Indicator if the coupon is applied on receipt or sales item level
couponId	The account coupon ID
discountElements > discountAmount	The applied discount amount
discountElements > discountPurposeCode	The discount purpose code
discountElements > manually	Indicator if the discount is given manually
position	The ordered position of the assignment
returned	Indicator if the coupon is returned

 

Summary

In this blog post, I explained how to configure an endpoint of type Generic for receipt forwarding. We forwarded a receipt and configured a job to repost receipts that are failed or not yet dispatched. The receipt export offers another possibility to download a set of receipts, either manually or in a scheduled manner to export them to a file or SFTP destination.

We discussed the structure of the receipt payload and differences in the structure between forwarding and export. Per type of object, receipt, tax item, sales item, payment item, charge element, cash desk closing and coupon assignment, we discussed the most important fields.

Feel free to share your comments and give feedback about the blog.