# SMS Receipts

This section is relevant to you if your flexEngage receipt services package includes support for sending receipts
via SMS.

## 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** — for merchants whose package includes SMS delivery.
* [Integration Testing Checklist](/receipts/testing-checklist.html) — validate your integration before launch.

## Configuring for SMS Support

The flexEngage team performs the following tasks in order for the merchant to be able to use SMS:

* The flexEngage team sets up the merchant account to support SMS receipts.
* The flexEngage team works directly with the merchant on provisioning the phone number to use (including short
  codes) as the "from" address for SMS receipt messages.
* The flexEngage team works directly with the merchant on setting up the content for the SMS messages.

## Sending the API Request for SMS

You would continue to call the Receipts API as you would for the other receipts. In order to send an SMS receipt
request, you will need to make the following changes to the values in the payload:

* **Do not** send the email address in the email address field (`customer.emailAddress`). Including an email
  address in the request will cause the receipt to be delivered by email AND sms.
  * You can either send a blank or null value, or you can remove the field from the payload.
* **Do not** send the area code in the area code field (`customer.telephone.areaCode`). You can either send a
  blank or null value, or you can remove the field from the payload.
* Add the mobile number in the local number field (`customer.telephone.localNumber`) in the following format: a
  plus sign, the country code and the area code. Do not include dashes. A few example formats:
  * US and Canada number: +12121234567
  * UK number: +447911123456
  * Ireland number: +353831234567
  * Mexico number: +521234567890
* Send the value *DigitalOnly* in the receipt type field (`receiptType`).

Below is an example payload for sending an SMS transaction. The affected fields are in **bold**. For a full
explanation of the payload fields and the valid values, reference the [Receipts API](/receipts-api.html):

<pre><code>{
  <strong>"customer": {
    "emailAddress": "",
    "telephone": {
      "areaCode": "",
      "localNumber": "+12121234567"
    }
  },</strong>
  "referenceId": null,
  "workstation": {
    "id": "889",
    "operator": "Joe",
    "associate": "Carl",
    "store": {
      "id": "99999",
      "name": "Jennifer Test Store",
      "address": {
        "typeCode": null,
        "addressLine1": "Alex Test",
        "city": "flexReceipts Headquarters",
        "territory": "FL",
        "postalCode": " 32701",
        "country": {
          "value": "US",
          "code": "US"
        },
        "postalCodeExtension": "1234"
      },
      "telephone": {
        "areaCode": "407",
        "localNumber": "5551212"
      }
    }
  },
  "mode": null,
  "header": null,
  <strong>"receiptType": "DigitalOnly",</strong>
  "barcodeType": "Code128",
  "barcodeNumber": null,
  "receiptDateTime": "2020-01-21T04:47:10-05:00",
  "loyalty": {
    "number": "23145",
    "customerName": "Joe Customer",
    "expirationDateTime": "2017-12-31",
    "balance": 45,
    "misc": "5 point until next offer"
  },
  "transactionType": "SaleTransaction",
  "relatedTransactionReference": null,
  "transactionNumber": "001",
  "items": [

    ],
    "netAmount": 0,
    "grossAmount": 0,
    "taxes": [
        {
            "description": "Sales Tax",
            "percent": 0.065,
            "taxableAmount": 0,
            "amount": 0,
            "taxTypeCode": "Sales"
        }
    ],
    "grandAmount": 0,
    "tenderApplied": 0,
    "changeDue": 0,
    "tenders": [
        {
            "tenderTypeCode": "Cash",
            "dateTime": null,
            "amount": 0,
            "creditDebit": null,
            "miscInfo": null,
            "currency": "USD"
        }
    ],
  "soldTo": {
    "address": {
      "typeCode": null,
      "addressLine1": "500 Main Street",
      "city": "Orlando",
      "territory": "FL",
      "postalCode": "32805",
      "country": {
        "value": "US",
        "code": "US"
      },
      "postalCodeExtension": null
    },
    "customerName": "Joe Customer",
    "customerNumber": 12312,
    "telephone1": {
      "areaCode": "407",
      "localNumber": "5555555"
    }
  },
  "additionalInfo1": null,
  "additionalInfo2": null,
  "additionalInfo3": null,
  "additionalInfo4": null,
  "additionalInfo5": null,
  "rawPosReceipt": null,
  "currency": "USD"
}</code></pre>

## Adding SMS Support to Front-End POS

### Receipt Selection

When a customer is offered a digital receipt, a dialog box (such as the example below) should be presented at the
POS to collect their mobile phone number and receipt option. For entering the mobile phone number, add support to
enter the country code, area code, and local number.

![Receipt Selection dialog with SMS support](/receipts/images/sms-receipt-selection-dialog.png)