> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getstell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identify wallet pass holders at the POS: scan or NFC tap

> Read a customer identifier from a barcode scan or an NFC tap (Apple VAS, Google Smart Tap) at checkout, with no Stell call in the checkout path.

In store, the pass identifies the customer at your POS. Identification is local. The scan or tap hands your POS an identifier it resolves against your own systems, with no Stell call in the checkout path, so checkout keeps working even if everything else is down. Your systems stay the ledger: points and balances are computed where they always were.

<Tabs>
  <Tab title="Barcode scan">
    The barcode carries the payload configured on your pass template, using placeholders such as `{{customer.externalId}}`, `{{customer.emailAddress}}`, or `{{customer.mobileNumber}}`, or set per pass with the API's `payload` field. Left unset, it falls back to the pass `id`. Point it at the identifier your POS can resolve, usually `externalId`. See [barcodes on pass templates](/pass-templates/barcodes) for the template side.

    ```mermaid theme={null}
    sequenceDiagram
        autonumber
        participant C as Customer
        participant P as Your POS
        participant B as Your backend
        participant S as Stell API
        C->>P: Presents pass, barcode scanned
        Note over P: Payload resolved locally, no Stell call
        P->>B: Sale settles, member identified
        B->>S: PATCH /v1/passes/{passId} with new loyaltyState
        B->>S: POST /v1/transactions (optional)
    ```
  </Tab>

  <Tab title="NFC tap">
    The customer taps once at the terminal, and payment and identification happen in the same gesture. Apple VAS and Google Smart Tap ride the contactless tap. No app to open, no barcode to aim at. The reader authenticates with merchant-specific keys and decrypts a per-tap payload, so it can't be screenshotted or replayed the way a barcode can.

    For NFC there is no template setting. Send the `payload` field when you issue the pass. Left unset, it falls back to the pass `id`. Point it at the identifier your POS can resolve, usually `externalId`, and keep it to **64 characters or fewer**. The same field also drives the barcode kept as a fallback.

    Two prerequisites, both arranged with Stell support:

    * **NFC pass enablement.** Apple VAS and Google Smart Tap activated for your program. Stell is a certified Apple VAS provider and handles the approvals and certificates.
    * **Terminal provisioning.** Your terminals must support VAS / Smart Tap and carry the right keys. The terminals and the vendor relationship are yours; confirm support and key setup with your terminal vendor.

    ```mermaid theme={null}
    sequenceDiagram
        autonumber
        participant C as Customer
        participant T as Terminal
        participant P as Your POS
        participant B as Your backend
        participant S as Stell API
        C->>T: Taps pass, Apple VAS / Google Smart Tap
        T->>P: Decrypted payload, your customer identifier
        P->>B: Sale settles, member identified
        B->>S: PATCH /v1/passes/{passId} with new loyaltyState
        B->>S: POST /v1/transactions (optional)
    ```
  </Tab>
</Tabs>

## After the sale

**Push the new balance to the pass.** [Update pass](/api-reference/passes/update-pass) with the new `loyaltyState`. Everything downstream of the scan or tap is identical for barcode and NFC.

**Optionally record the visit.** [Create transaction](/api-reference/transactions/create-transaction) needs only `passId` and `type`. Everything else is optional, so send what your POS knows:

* `type`: what happened to the pass, for example `PURCHASE`, `REDEMPTION`, or `SCAN_ONLY`.
* `channel` (`IN_STORE`) and `tapMode` (`SINGLE_TAP` when pass and payment rode one tap, `DOUBLE_TAP` for separate taps, `NONE` without a terminal).
* `instrument`: how the pass was presented. `QR` for a barcode scan, `APPLE_VAS` or `GOOGLE_SMART_TAP` for a tap.
* `status` (`APPROVED`, `DENIED`, `FAILED`, or `PENDING`) with a `statusReason` when it explains a denial or failure.
* `pointsEarned`, `pointsSpent`, and your `reference` (receipt number).
* `storeId` and `terminalId`, if you track them.
* `payment`: the payment side, with `method` (`APPLE_PAY`, `CARD`, `VIPPS`, and so on), `amount`, and PSP references.
* `additionalData`: POS metadata such as register ID, line items, merchant category code, and raw POS or PSP data. See the [request schema](/api-reference/transactions/create-transaction) for the full list of accepted keys.

Recorded transactions appear in the portal's [Transaction Log](/transactions/overview). Staff can then investigate usage without leaving Stell.

**Choosing hardware?** The [reader directory](https://getstell.com/readers) on getstell.com lists payment terminals and NFC readers that read Apple Wallet and Google Wallet passes. For the business case behind tap at the till, read [NFC loyalty identification](https://getstell.com/articles/nfc-loyalty-identification-how-tap-at-the-till-works).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.