# Integration Testing Checklist

Use this checklist alongside the [Receipts API Integration Guide](/receipts/receipts-integration-guide.html) to
validate a POS integration before it goes live, and to help diagnose issues in an existing integration.

## In This Guide

* [Receipts API Integration Guide](/receipts/receipts-integration-guide.html) — authentication, request/response
  flow, error handling, and best practices.
* [Request Field Reference](/receipts/request-reference.html) — field-by-field usage notes for headers, discounts,
  loyalty, tenders, taxes, items, custom fields, and more.
* [Receipt Data Elements](/receipts/receipt-data-elements.html) — how request fields map to sections of a rendered
  receipt (orders, returns, totals, deposits, payment history, and more).
* [Point of Sale UI Guidelines](/receipts/pos-ui-guidelines.html) — recommended configuration options and UI flow.
* [Printed Offers](/receipts/printed-offers.html) — for merchants whose package includes printed offers.
* [SMS Receipts](/receipts/sms-receipts.html) — for merchants whose package includes SMS delivery.
* **Integration Testing Checklist** — validate your integration before launch.

Items are grouped by priority:

| Priority | Meaning |
|---|---|
| Critical | Must be fixed before launch — these cause missed or incorrect receipts. |
| Important | Should be fixed for production quality, but won't block a launch. |
| Nice to have | Worth doing, but can be deferred to a later iteration. |

## Pre-Integration Validation

**POS data quality** (critical unless noted):

* All required transaction fields are populated in the POS.
* Customer email addresses are accessible via the POS API or database.
* Item details include name, price, and SKU/UPC code (important).
* Tax calculations are exposed at both the line-item and transaction level (important).

**Data format consistency** (critical unless noted):

* Monetary amounts use a consistent representation (watch for cents vs. dollars).
* Date/time fields use a consistent format across POS tables.
* Phone numbers include area and country codes (important).
* Item descriptions don't contain unescaped special characters (`\n`, `\t`, quotes) (important).

**Integration method:**

* Confirm whether the POS supports real-time calls or requires polling/batching.
* Identify every database table needed to assemble a complete transaction.
* Confirm the POS's own API rate limits and authentication requirements.
* Test POS responsiveness during high-traffic periods.

## Request Validation

**Core transaction data:**

* `merchantId` matches the identifier flexEngage provided.
* `transactionNumber` is unique and consistently formatted.
* `receiptDateTime` is in ISO 8601 format.
* `transactionType` is set correctly (`SaleTransaction`, `Return`, etc.).

**Customer information:**

* `customer.emailAddress` is present whenever a digital receipt is requested, and passes RFC 5322 validation.
* Phone numbers (if provided) include a country code.
* Customer data isn't duplicated across the buyer and loyalty sections.

**Items:**

* At least one item is present in `items`.
* Each item has a name, price, and quantity; SKU/UPC is included when available.
* Sub-items are nested correctly rather than flattened.

**Mathematical accuracy:**

* Item amounts sum to the transaction subtotal.
* Tax amounts match the calculated percentages, and discounts are subtracted correctly.
* Total tender equals the transaction grand total, and change due is calculated correctly.
* All monetary amounts use the same currency code, matching the merchant's configured currency.
* Split and partial-tender transactions (cash + card, multiple cards, etc.) allocate each tender's amount
  correctly rather than duplicating or dropping a portion of the total.

**Transaction consistency:**

* `receiptDateTime` is not in the future.
* Return amounts don't exceed the original purchase amount.
* Returns and exchanges use the proper return/exchange fields rather than a plain sale transaction.
* Voided transactions are handled appropriately (not sent as a completed sale).

**Receipt type logic:**

* `receiptType` matches both customer preference and the data actually available (for example, `DigitalOnly`
  requires a valid email address).
* `DigitalAndPaper` triggers both the email send and the local paper print.
* `NoReceipt` is only used where appropriate for the transaction type.

## Avoiding Duplicates and Common Field-Mapping Errors

* Generate and send a `requestId` on every request, and confirm retry logic reuses it rather than generating a
  new one — this is what makes `409` responses safe to ignore instead of a sign something went wrong.
* Confirm the same transaction is never submitted more than once outside of an intentional retry.
* Don't duplicate customer information across the buyer and loyalty sections, or provide phone numbers in
  multiple formats.
* Send dates as ISO 8601 strings, amounts and quantities as numbers, and booleans as `true`/`false` — not as
  strings.
* Check conditional requirements: a loyalty number implies a required customer email; a gift card or credit card
  payment implies its own required sub-fields; a signature requirement implies signature data or a URL.

## Handling Responses

* **`200`** — capture the returned receipt ID, show the appropriate confirmation, print paper if required, and
  mark the transaction as "receipt sent" in the POS.
* **`422`** — log the field-specific errors with the transaction, correct the data, and fall back to a paper
  receipt if the retry also fails.
* **`409`** — treat as success, not a failure; don't retry, and confirm the POS reflects the original delivery.
* **`500`** — retry with exponential backoff up to a maximum attempt count, then fall back to paper.

## Production Readiness

**Performance:**

* API calls perform acceptably during peak transaction volume, with timeouts sized for the business (not so long
  they block checkout).
* Connection pooling is configured, and a failed or slow request never blocks POS transaction completion.

**Network resilience:**

* The offline/retry queue works correctly and drains once connectivity returns.
* Network timeouts and partial failures are handled without crashing the POS application.

**Monitoring:**

* Receipt success/failure rates and API response times are tracked, with alerting on error-rate spikes.
* Complete request/response data is logged for troubleshooting — excluding sensitive cardholder data — with a
  correlation ID linking the POS transaction to the flexEngage receipt.

## Customer Experience

* Test emails are delivered across major providers, render correctly on mobile, and don't trigger spam filters.
* Unsubscribe and email preference management work correctly for customers who opt out.
* Paper receipts print automatically when digital delivery fails, and customers can request a resend.
* Receipt language matches customer preference; currency and date formatting follow local conventions; special
  characters render correctly.

## Compliance and Security

* Payment card numbers are never included in receipt data beyond the last four digits.
* Customer PII is handled per applicable privacy regulations, and all traffic uses TLS 1.2 or higher.
* Delivery attempts (including failures and reason codes) are logged, and customer consent for digital receipts
  is recorded per your data retention policy.

## Test Data to Cover

Exercise these transaction types before launch:

* Simple cash sale, credit card sale with tip, sale with discounts and tax.
* Return/exchange, multi-tender (cash + card), loyalty transaction, gift card purchase and redemption.
* International transaction, if applicable to your merchant configuration.

And these customer profiles:

* Email only; email and phone; loyalty membership; preference for paper receipts; international phone number;
  long name/address values.

Coordinate test scope and timing with your [flexEngage representative](mailto:support@flexengage.com) — testing
must use real email addresses, and any high-volume or automated testing against production requires prior written
approval.