Punchh Single Scan Code API

openapi: 3.2.0
info:
  title: Mobile Single Scan Code API
  version: '1.0'
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
  description: Punchh provides a robust platform for offering loyalty programs to customers.
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Single Scan Code
paths:
  /api2/mobile/single_scan_tokens:
    parameters: []
    post:
      parameters:
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/User-Agent'
      - $ref: '#/components/parameters/punchh-app-device-id'
      - $ref: '#/components/parameters/Authorization'
      summary: Generate Single Scan Code or Short Code
      description: 'This API facilitates the single-scan flow functionality, allowing a user to generate a single-scan code from the mobile app for making a payment, redeeming a discount, adding a tip, or any combination of these in a single transaction at the POS. The API returns a single scan code containing a UUID string in the response.


        For more information, see Single Scan Flow.


        **Note**: This mobile API endpoint (`POST {server-name}/api2/mobile/single_scan_tokens`) is the same as the mobile API endpoint used to generate a one-time passcode (OTP) for use with Redemptions 2.0. When using this API with Redemptions 2.0, the following offers parameters must NOT be included with the request body:

        - `reward_id`

        - `redeemable_id`

        - `banked_reward_amount`

        - `coupon`

        - `redeemable_card_count`

        - `subscription_id`


        ### Loyalty Short Code Flow


        This API also supports the loyalty short code flow for drive-thru identification and payment. The loyalty identification at drive-thru, single scan flow and drive-thru payment using short code payment (using SSF) must be enabled for the business to allow payments using the short code.


        The API accepts two additional parameters in the request body: a boolean parameter, `short_code`, and `location_id` to generate a short code.


        When the `short_code` parameter is set to `true`, the API generates a short alphanumeric code along with a single scan code. The single scan code is not returned in the API response for the loyalty short code flow. It is stored in the Punchh backend and associated with the short code.


        Users can share the short code verbally at the drive-thru window for faster account look-up at the POS.


        In addition to the short code, the API response also includes the `location_id` for which the short code is generated, `expiring_at`, which indicates when the short code expires, and `new_short_code_generated`, which indicates whether a new short code has been generated.


        When `short_code` is set to false, the API follows the legacy single scan token flow and returns only a single scan code for transactions.


        Contact your Punchh representative to update these Punchh platform configuration.


        When the POS calls the User Look-up API with the short code, Punchh retrieves the single scan code associated with the short code to look up the user, the rewards, and the payment selected by the user when generating the short code. The User Look-up API includes the `single_scan_code` in the response, which the POS can use for further actions such as check-in, redemptions, and payments.


        **Configuration Resolution Logic**


        Single scan code generation follows this configuration priority:

        1. Location-level single scan flow configuration.

        2. If not configured at location level, the business-level single scan flow configuration is evaluated.


        **When `short_code` = `true`:**

        - The system checks whether the short code and single scan flow are enabled for the location.

        - If not configured at the location level, the business-level configuration is evaluated.

        - If neither the location nor the business has the required short code and single scan flow configurations enabled, the API returns a 422 feature-disabled error. If the `location_id` value is invalid or missing in the request, the API returns a missing location ID error.


        **When `short_code` = `false`:**

        - The legacy single scan code flow is triggered and a `single_scan_code` is returned.

        - The token type is selected based on the location-level configuration (if present), otherwise business-level configuration is used.'
      operationId: mobile_gen_ssc
      tags:
      - Single Scan Code
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  single_scan_code:
                    type: string
                    description: Single scan code of the user to be used in the single scan flow at the POS
                  expires_in:
                    type: string
                    format: date-time
                    description: Date/time when the single scan code expires and can no longer be used at the POS, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
                  created_at:
                    type: string
                    format: date-time
                    description: Date/time when the single scan code was created in the system, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
                  short_code:
                    type: string
                    description: Short alphanumeric code for drive-thru identification. Returned when the `short_code` request parameter is set to true.
                  location_id:
                    type: number
                    description: ID of the location for which the short code is requested. Returned when the `short_code` request parameter is set to true.
                  new_short_code_generated:
                    type: boolean
                    description: Indicates whether a new short code is generated for the single scan code. Returned when the `short_code` request parameter is true. When `new_short_code_generated` is true, a new short code is generated and assigned to the single scan code; when false, a previously active short code is reassigned to a new single scan code. Note that, in the loyalty short code flow, the single scan code is not returned in the API response.
                  expiring_at:
                    type: string
                    format: date-time
                    description: Date/time when the short code expires and can no longer be used at the drive-thru, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. This parameter is returned when the `short_code` request parameter is set to true.
              examples:
                Response Example:
                  value:
                    single_scan_code: SINGLE_SCAN_CODE_GOES_HERE
                    expires_in: '2022-06-08T10:19:52Z'
                    created_at: '2022-06-08T10:14:52Z'
                Short Code Response:
                  value:
                    short_code: JII8
                    location_id: 12345
                    expiring_at: '2026-02-13T11:44:11+05:30'
                    new_short_code_generated: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      missing_required_param:
                        type: string
              examples:
                'Response Example: Bad Request (blank client field)':
                  value:
                    errors:
                      missing_required_param_name: Required parameter missing or the value is empty
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      unauthorized:
                        type: array
                        items:
                          type: string
              examples:
                'Response Example: Unauthorized Request (Incorrect client value)':
                  value:
                    errors:
                      unknown_client:
                      - Client ID is incorrect. Please check client param or contact us
                Unauthorized (invalid or missing access token):
                  value:
                    errors:
                      unauthorized:
                      - An active access token must be used to query information about the current user.
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
              examples:
                Response Example (invalid payment_type value):
                  value:
                    errors: Invalid Payment Type
                Short code feature disabled for location:
                  value:
                    errors: This feature is currently turned off for this location. Please reach out to the Punchh Support team for more information.
                Missing location_id for short code:
                  value:
                    errors: While requesting for short code, Location Id is mandatory.
      x-stoplight:
        id: 1b70514f6ead9
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                payment_type:
                  type: string
                  description: Payment type selected by the user when generating the single scan code. Valid values are `GiftCard`, `CreditCard`, or `recurring`. The payment type is recurring when the user selects a saved payment card from the mobile application for payments.
                gift_card_uuid:
                  type: string
                  description: The user's gift card number. Required if the payment type is gift card.
                transaction_token:
                  type: string
                  description: Unique digital identifier/token of the user's credit card, or UUID of the saved payment card if the payment type is recurring. Required if the payment type is credit card or recurring.
                reward_id:
                  type: string
                  description: Unique ID of a reward, or a comma-separated list of reward IDs if multiple rewards are selected by the user for redemption
                redeemable_id:
                  type: string
                  description: Unique ID of a redeemable, or a comma-separated list of redeemable IDs if multiple redeemables are selected by the user for redemption
                subscription_id:
                  type: string
                  x-stoplight:
                    id: jz57t3l1413j4
                  description: Unique ID of a subscription, or a comma-separated list of subscription IDs if multiple subscriptions are selected by the user for redemption
                banked_reward_amount:
                  type: string
                  description: Amount of banked currency selected by the user for redemption
                coupon:
                  type: string
                  description: User-specific dynamically generated unique coupon codes that the POS system automatically applies in a single scan, or a comma-separated list of unique coupons if multiple coupons are selected by the user for redemption
                redeemable_card_count:
                  type: string
                  description: Number of redeemable cards selected by the user for redemption
                tip:
                  type: string
                  description: Amount that the user selected as a tip
                short_code:
                  type: boolean
                  description: Indicates whether short code flow should be used. When set to `true`, the API follows the short code flow and returns a short code for drive-thru identification and payment. When set to `false`, the API follows the legacy single scan token generation flow and returns only a single scan code for transactions. Contact your Punchh representative to update this Punchh platform configuration.
                location_id:
                  type: number
                  description: ID of the location for which the short code is requested. Required when `short_code` is `true` for short code and single scan code generation.
              required:
              - client
            examples:
              Credit Card:
                value:
                  client: CLIENT_GOES_HERE
                  payment_type: CreditCard
                  transaction_token: TRANSACTION_TOKEN_GOES_HERE
                  redeemable_id: REDEEMABLE_ID_GOES_HERE
                  reward_id: REWARD_ID_GOES_HERE
                  subscription_id: SUBSCRIPTION_ID_GOES_HERE
                  coupon: COUPON_CODE_GOES_HERE
                  tip: '1'
              Gift Card:
                value:
                  client: CLIENT_GOES_HERE
                  payment_type: GiftCard
                  gift_card_uuid: GIFT_CARD_UUID_GOES_HERE
                  reward_id: REWARD_ID_GOES_HERE
                  coupon: COUPON_CODE_GOES_HERE
                  redeemable_card_count: '2'
                  tip: '1'
              Recurring:
                value:
                  client: CLIENT_GOES_HERE
                  payment_type: recurring
                  transaction_token: SAVED_CARD_UUID_GOES_HERE
                  reward_id: REWARD_ID_GOES_HERE
              Short Code (Drive-Thru):
                value:
                  client: CLIENT_GOES_HERE
                  payment_type: GiftCard
                  gift_card_uuid: GIFT_CARD_UUID_GOES_HERE
                  reward_id: REWARD_ID_GOES_HERE
                  short_code: true
                  location_id: 12345
components:
  parameters:
    Authorization:
      schema:
        type: string
        default: Bearer ACCESS_TOKEN_GOES_HERE
      name: Authorization
      in: header
      description: Used to authorize the request with access_token. It should be supplied as `Bearer ACCESS_TOKEN_GOES_HERE`.
      required: true
    punchh-app-device-id:
      schema:
        type: string
        default: APP_DEVICE_ID_GOES_HERE
      name: punchh-app-device-id
      in: header
      required: true
      description: The app device ID helps Punchh identify each device so that certain rewards can be awarded individually to each device instead of per user. For example, the sign-up reward is given to each device ID to prevent fraudulent sign-ups so that a user cannot do repeated sign-ups from a single device to get rewards. It should not change even if the user resets a device. See the [sample code](/docs/dev-portal-mobile/56657769b1422-headers-and-caching#generating-the-punchh-app-device-id-header) to generate the punchh-app-device-id header.
    User-Agent:
      schema:
        type: string
        default: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version)
      in: header
      name: User-Agent
      description: Used to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see [User Agent](/docs/dev-portal-mobile/additional-topics/user-agent).
      required: true
    Content-Type:
      schema:
        type: string
        default: application/json
      name: Content-Type
      in: header
      description: Set this header to <b>application/json</b>.
      required: true
    Accept-Language:
      schema:
        type: string
        default: en
      name: Accept-Language
      in: header
      description: Preferred language
    signature:
      schema:
        type: string
        default: '{{$$.env.signature}}'
      name: x-pch-digest
      in: header
      description: The [signature](/docs/dev-portal-mobile/additional-topics/signature-sha256) for the API call
      required: true
x-stoplight:
  id: bf6eddb435209
x-ext-urls: {}