Review the complete JSON in the Receipts API reference for complete information. This section only focuses on areas that require special attention. For the overall integration flow, see the Receipts API Integration Guide; for how these fields map to sections of a rendered receipt, see Receipt Data Elements.
Customer Information is required to uniquely identify the customer and associate them to the transaction. Send all types of Customer Information available, as they can be used to uniquely identify the customer.
If a customer requests a digital receipt sent to one’s email (‘Digital Only’ or ‘Digital and Paper’), an email address must be sent.
| SAMPLE | NOTES |
|---|---|
|
Digital receipt transactions ('Digital Only' & 'Digital and Paper') REQUIRE an email address. 'Paper Only' receipt transactions can set the "emailAddress" element to null if no email address is on file. |
If the customer record has a phone number, it should be sent.
| SAMPLE | NOTES |
|---|---|
|
US phone numbers should use both areaCode and localNumber and send only numeric values. |
NOTE: If your flexEngage package includes SMS support, the content format is different. Refer to SMS Receipts for details on how to send an SMS number.
The JSON contains information about the receipt and transaction. Send as much of this information as possible. See the Receipts API reference for details about the elements that should be sent.
The mode field flags the environment or purpose of a transaction:
Production — a live, real transaction.Test — a test transaction, sent while validating your integration.Training — a demo/training transaction, for use in staff training scenarios.Coordinate with your flexEngage representative on how each mode is handled on their end (for example, whether
Test/Training transactions are excluded from merchant analytics and reporting).
flexEngage has a “header” element in the JSON that allows multi-line text at the top of the receipt in a location determined by the receipt template. This is typically used for dynamic text that needs to appear for special cases, such as employee purchase information or “Customer Receipt Copy”. “header” supports “\n” for a line break and “\t” for a tab.
| EXAMPLE | WOULD DISPLAY AS |
|---|---|
|
Customer Receipt Copy Employee Discount |
flexEngage provides additionalInfo1, additionalInfo2, additionalInfo3, additionalInfo4 and additionalInfo5 multi-line elements for display at locations determined by the receipt template. This can be dynamic text sent by the POS (e.g., ***You Saved $10.00***)
| EXAMPLE | WOULD DISPLAY AS |
|---|---|
|
We Appreciate Your Business! *** You Saved $10.00 *** |
flexEngage supports multiple transaction level discounts (promos) per receipt and allows for custom labels for each discount (e.g., “AARP Discount”)
| EXAMPLE | WOULD DISPLAY AS |
|---|---|
|
10% Discount (10.00) AARP Discount (15.00) |
If a loyalty number is associated with the customer, send as much loyalty information as is available. flexEngage collects the following loyalty information:
| SAMPLE | NOTES |
|---|---|
|
|
For credit/debit transactions, send as much info as possible:
| SAMPLE | NOTES |
|---|---|
|
|
flexEngage supports sending a BASE64BINARY image to be displayed on receipts. The signature areas that are available are:
| EXAMPLE | NOTES |
|---|---|
|
Signatures are available for: Tenders, Terms, and Transaction Signature.
|
flexEngage supports adding dynamic links in various places of the receipt data. Multiple links are available for any section that supports Supporting Documents.
| EXAMPLE | NOTES |
|---|---|
|
|
flexEngage supports multiple multi-line text blocks for various types of terms and conditions. The terms can be sent with or without a BASE64BINARY signature image and date to be displayed on receipts. A link can be added as well.
| EXAMPLE | NOTES |
|---|---|
|
|
flexEngage supports multiple tender types per receipt (i.e., Cash, Visa, Check). Each tender type now has the following structure:
| SAMPLE | NOTES |
|---|---|
|
See the Receipts API reference for complete information on tender types. The JSON on the left shows a transaction that was tendered with cash, a gift card, and a credit card. |
flexEngage supports multiple taxes (e.g., Local, VAT) per receipt. Each tax has the following structure:
| EXAMPLE | WOULD DISPLAY AS / NOTES |
|---|---|
|
 Not sending description (or setting to null) results in the word "Tax:" being printed on the digital receipt. |
flexEngage supports multiple fees per receipt. It has the following structure:
| EXAMPLE | WOULD DISPLAY AS / NOTES |
|---|---|
|
 amount is required for the fee to display on receipt. |
Send as much of this information as possible for each item on the receipt. Limiting information only to what is displayed on the paper receipt limits the type of data that can be used by head office reporting. See the Receipts API reference for details about the elements to be sent.
Use price for the Unit Price if it is available. Use total for the Total Amount the customer is paying for the quantity purchased.
| SAMPLE | NOTES |
|---|---|
|
Note: flexEngage DOES NOT calculate totals or amounts. Calculations need to happen before sending the value to flexEngage through the payload.
In the example JSON, there are 2 items, $5 each and a $1 off coupon. The total for the item would be $9. |
Use the priceNotation element for any codes added to the final price on the printed receipt (e.g., “N” for non-taxable).
| EXAMPLE | WOULD DISPLAY AS |
|---|---|
|
NOTE: The exact display will depend upon your receipt template and based upon your requirements. |
flexEngage supports multiple item level discounts per receipt and allows for custom labels for each discount (e.g., “Member Discount”)
| EXAMPLE | WOULD DISPLAY AS |
|---|---|
|
Coupon (1.00) Member Discount (2.00) |
Several elements in the flexEngage JSON support multi-line text with line breaks and tabs using a ‘\n’ newline symbol and ‘\t’ tab symbol:
| EXAMPLE | WOULD DISPLAY AS |
|---|---|
|
Thanks for Shopping! Have A Great Day Bye |
| header | signature.text | additionalInfo2 |
| items.description | deliveryPickup.instructions | additionalInfo3 |
| miscInfo / miscText | terms.description | additionalInfo4 |
| loyalty.misc | additionalInfo1 | additionalInfo5 |
A few fields have validation constraints worth checking client-side before submitting a request:
transactionNumber — 1 to 50 characters; alphanumeric plus hyphens and underscores.emailAddress — must be RFC 5322 compliant.receiptDateTime — ISO 8601 format, with timezone.flexEngage supports the use of custom fields at the root level of the JSON object and also on any item objects. The name of a custom field should be alphanumeric (i.e. no special characters, spaces, etc). The value of a custom field can be an integer, decimal, boolean, string, list, or object.
NOTE: When adding custom fields to the payload that need to appear on the receipt, you must let the flexEngage representative know so the representative can coordinate with the appropriate flexEngage teams to ensure the fields are added on the receipt.
Below is an example of a payload with custom properties in bold. The names are illustrative of the type of value but this is not necessary (Note: you should name the fields based on their business purpose).
{
"customer":{
"emailAddress":"customer@example.com"
},
"aCustomString":"this is a custom string",
"aCustomNumber":1,
"aCustomDecimal":1.1,
"aCustomBoolean":true,
"aCustomList":["a", "b","c","d"],
"aCustomObject":{
"prop1":"Custom prop within a custom object",
"prop2":"Custom prop within a custom object"
},
"workstation":{
"id":"ID",
"store":{
"id":"storeId",
"name":"storeName",
"address":{
"addressLine1":"StoreAddressLine1",
"city":"StoreCity",
"territory":"StoreTerritory",
"postalCode":"00000",
"country":{
"value":"StoreCountry",
"code":"US"
}
}
}
},
"receiptType":"DigitalAndPaper",
"receiptDateTime":"2013-11-10T15:15:17-05:00",
"transactionType":"SaleTransaction",
"transactionNumber":"001",
"items":[
{
"name":"ItemName",
"sku":"SKUNumber",
"upc":"UPCNumber",
"price":1.0,
"total":1.0,
"quantity":{
"value":1
},
"aCustomString":"this is a custom string",
"aCustomNumber":1,
"aCustomDecimal":1.1,
"aCustomBoolean":true,
"aCustomList":["a", "b","c","d"],
"aCustomObject":{
"prop1":"Custom prop within a custom object",
"prop2":"Custom prop within a custom object"
}
}
],
"grandAmount":0.0,
"tenders":[
{
"tenderTypeCode":"Cash",
"amount":0.0
}
]
}