CRM and CX Blogs by SAP
Stay up-to-date on the latest developments and product news about intelligent customer experience and CRM technologies through blog posts from SAP experts.
cancel
Showing results for 
Search instead for 
Did you mean: 
former_member280904
Participant
3,021
Hello reader,

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



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. 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 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.

About me: 
My name is Armin Zamani. I work for SAP SE, Germany. My current role is Senior Developer for SAP Customer Checkout.