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
| 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.
Click on Add to create a destination.
Enter destination details
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/stockoverviewIn 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/pingyou 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.
| 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.
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
| 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”
Configure the receipt export settings.
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.
Configure SFTP destination for the receipt export
To export receipts on a regular basis, an SFTP destination shall be configured.
- Open the tile “Communication systems”, select the respective communication system, and navigate to the tab “Destinations”. Click on the “Add” button.
- Select the destination type “SFTP”
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.
- Open the Jobs tile
- Select the type “Receipt: Export”
- 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.
| 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 |
