Generate Single Scan Code or Short Code

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:

Location-level single scan flow configuration.
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.

Headers

x-pch-digest
Type: string
required

The signature for the API call
Content-Type
Type: string
required

Set this header to application/json.
Accept-Language
Type: string

Preferred language
User-Agent
Type: string
required

Used to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see User Agent.
punchh-app-device-id
Type: string
required

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 to generate the punchh-app-device-id header.
Authorization
Type: string
required

Used to authorize the request with access_token. It should be supplied as Bearer ACCESS_TOKEN_GOES_HERE.

Body

application/json

client
Type: string
required

OAuth client ID provided by the business
banked_reward_amount
Type: string

Amount of banked currency selected by the user for redemption
coupon
Type: string

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
gift_card_uuid
Type: string

The user's gift card number. Required if the payment type is gift card.
location_id
Type: number

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.
payment_type
Type: string

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.
redeemable_card_count
Type: string

Number of redeemable cards selected by the user for redemption
redeemable_id
Type: string

Unique ID of a redeemable, or a comma-separated list of redeemable IDs if multiple redeemables are selected by the user for redemption
reward_id
Type: string

Unique ID of a reward, or a comma-separated list of reward IDs if multiple rewards are selected by the user for redemption
short_code
Type: boolean

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.
subscription_id
Type: string

Unique ID of a subscription, or a comma-separated list of subscription IDs if multiple subscriptions are selected by the user for redemption
tip
Type: string

Amount that the user selected as a tip

Responses

application/json
application/json
application/json
application/json

post/api2/mobile/single_scan_tokens

curl https://SERVER_NAME_GOES_HERE.punchh.com/api2/mobile/single_scan_tokens \
  --request POST \
  --header 'x-pch-digest: {{$$.env.signature}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept-Language: en' \
  --header 'User-Agent: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version)' \
  --header 'punchh-app-device-id: APP_DEVICE_ID_GOES_HERE' \
  --header 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
  --data '{
  "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"
}'

Show Schema

{
  "single_scan_code": "SINGLE_SCAN_CODE_GOES_HERE",
  "expires_in": "2022-06-08T10:19:52Z",
  "created_at": "2022-06-08T10:14:52Z"
}