info:
title: Mobile 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. When a business
integrates its back-end with the Punchh server, the Punchh APIs become instrumental in executing loyalty
programs for enrolled customers, primarily via business-branded mobile apps and websites tailored
by Punchh.
To establish integration with the Punchh APIs, you need to understand how they are invoked and what
responses are returned by the Punchh server. You can call APIs using any suitable API test client,
such as Postman. Thus, the response to every API call made in Postman under a chosen environment (in
app and/or platform) is reflected in the app and/or platform.'
paths:
/api2/mobile/users/login:
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'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
access_token:
$ref: '#/components/schemas/access_token-Object'
user:
$ref: '#/components/schemas/User-object'
examples:
default:
value:
access_token:
token: ACCESS_TOKEN_GOES_HERE
seconds_to_expire: null
revoked_at: null
refresh_token: REFRESH_TOKEN_GOES_HERE
scopes: []
user:
address: ''
anniversary: '2013-02-16'
avatar_remote_url: null
birthday: '1999-01-01'
city: ''
communicable_email: test@example.com
created_at: '2019-01-11T09:08:25Z'
email: test@example.com
email_verified: false
facebook_signup: null
apple_signup: null
apple_uid: null
favourite_location_ids: 306082,333070,304374
favourite_store_numbers: 12345,0604,1234
fb_uid: null
first_name: FIRST_NAME_GOES_HERE
gender: ''
has_generated_fb_email: false
last_name: LAST_NAME_GOES_HERE
marketing_email_subscription: true
marketing_pn_subscription: true
migrate_status: false
passcode_configured_for_giftcards: false
phone: '1111111111'
profile_field_answers:
test1: Option 1
referral_code: REFERRAL_CODE_GOES_HERE
referral_path: URL_GOES_HERE
secondary_email: ''
state: ''
superuser: false
terms_and_conditions: true
title: ''
updated_at: '2020-04-29T04:18:24Z'
user_as_qrcode: QR_CODE_GOES_HERE
user_code: P11111111
user_id: 111111111
preferred_locale: en
user_relations: []
zip_code: null
verification_mode: null
sms_subscription: false
apple_pass_url: APPLE_PASS_URL_GOES_HERE
google_pass_url: GOOGLE_PASS_URL_GOES_HERE
user_joined_at: '2019-01-11T09:08:25Z'
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
missing_required_param:
type: array
items:
type: string
examples:
Bad Request (blank email field):
value: "{\n \"errors\": {\n \"missing_required_param\": [\n \"Required parameter\
\ missing or the value is empty: email\"\n ]\n }\n}"
Bad Request (invalid language):
value: "{ \n \"errors\":{ \n \"invalid_language\":[ \n \"Unknown/Invalid\
\ locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es.\"\n\
\ ]\n }\n}"
Bad Request (missing parameter):
value: "{ \n \"errors\":{ \n \"missing_required_param\":[ \n \"Required\
\ parameter missing or the value is empty: client\"\n ]\n }\n}"
'401':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
unknown_client:
type: array
items:
type: string
examples:
default:
value:
errors:
unknown_client:
- Client ID is incorrect. Please check client param or contact us.
'412':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
invalid_signature:
type: array
items:
type: string
examples:
application/json; charset=utf-8:
value:
errors:
invalid_signature:
- Signature doesn't match. See https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
'422':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
invalid_email_password:
type: array
items:
type: string
examples:
default:
value:
errors:
invalid_email_password:
- Sorry, Invalid Email/Password.
summary: Sign in
description: 'Logs a user into the app of a business and returns the user''s information in the
response
'
operationId: mobile_signin
tags:
- Users
x-stoplight:
id: c1be403d96bc5
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
user:
type: object
properties:
email:
type: string
description: Email address of the user
password:
type: string
description: Password of the user
apn_token:
type: string
description: Apple push-notification token that allows push notifications to be
received on the registered device of the user
gcm_token:
type: string
description: Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) token
that allows push notifications to be received on the registered device of the
user
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
user:
email: test@example.com
password: PASSWORD_GOES_HERE
/api2/mobile/single_scan_tokens:
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. \n\nFor more information, see [Single Scan\
\ Flow](/docs/dev-portal-pos/54e5a71a7205c-single-scan-flow).\n\n**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](/docs/dev-portal-mobile/apis/mobile-redemptions-2-0-new-api/post/api2/mobile/single_scan_tokens).\
\ When using this API with Redemptions 2.0, the following offers parameters must NOT be included\
\ with the request body:\n- `reward_id`\n- `redeemable_id`\n- `banked_reward_amount`\n- `coupon`\n\
- `redeemable_card_count`\n- `subscription_id`\n\n### Loyalty Short Code Flow\n\nThis 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.\n\nThe\
\ API accepts two additional parameters in the request body: a boolean parameter, `short_code`,\
\ and `location_id` to generate a short code. \n\nWhen 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.\n\nUsers can share the short code verbally at the\
\ drive-thru window for faster account look-up at the POS. \n\nIn 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.\n\nWhen `short_code` is set to false, the API follows\
\ the legacy single scan token flow and returns only a single scan code for transactions.\n\n\
Contact your Punchh representative to update these Punchh platform configuration.\n\nWhen the\
\ POS calls the [User Look-up API](https://developers.partech.com/docs/dev-portal-pos/apis/pos-api/tag/point-of-sale/get/api/pos/users/search)\
\ 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.\n\n**Configuration Resolution\
\ Logic**\n\nSingle scan code generation follows this configuration priority:\n1. Location-level\
\ single scan flow configuration.\n2. If not configured at location level, the business-level\
\ single scan flow configuration is evaluated.\n\n**When `short_code` = `true`:**\n- The system\
\ checks whether the short code and single scan flow are enabled for the location.\n- If not configured\
\ at the location level, the business-level configuration is evaluated.\n- 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.\n\n**When `short_code` = `false`:**\n\
- The legacy single scan code flow is triggered and a `single_scan_code` is returned.\n- 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
parameters: []
/api2/mobile/payment_cards:
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'
- $ref: '#/components/parameters/Accept'
summary: Create a Payment Card
description: Creates and saves a payment card for a user. This API is triggered when the user saves
the payment card on the mobile application.
operationId: create_api2-mobile-payment_cards
tags:
- Payment Cards
responses:
'200':
description: Payment Card Added
content:
application/json:
schema:
type: object
properties:
uuid:
type: string
description: Saved payment card UUID
nickname:
type: string
description: Saved payment card nickname, as set by the user
preferred:
type: boolean
description: This value determines whether this saved payment card will be selected
as the default card or not when the user makes a payment through the mobile application.
If the value is set to true, this card will be selected as the default card for
payments. Valid values are true or false.
card_details:
type: object
description: User's saved payment card details
properties:
name_on_card:
type: string
description: Cardholder name
card_type:
type: string
description: Saved payment card type (e.g., Visa, Mastercard, Amex, etc.)
cc_4:
type: string
description: Last 4 digits of the saved payment card
expiry_month:
type: string
description: Expiration month of the saved payment card
expiry_year:
type: string
description: Expiration year of the saved payment card
examples:
default:
value:
uuid: <UUID_GOES_HERE>
nickname: <NICKNAME_GOES_HERE>
preferred: true
card_details:
name_on_card: <CARDHOLDER_NAME_GOES_HERE>
cc_4: '4242'
card_type: Visa
expiry_month: '02'
expiry_year: '28'
'400':
description: Bad Request (missing or blank required parameter)
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
missing_required_param:
type: string
examples:
Bad Request (missing or blank required parameter):
value:
errors:
missing_required_param_name: Required parameter missing or the value is empty
'401':
description: Unauthorized Request (incorrect client value)
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
unauthorized:
type: array
items:
type: string
examples:
Unauthorized Request (incorrect client value):
value:
errors:
unknown_client:
- Client ID is incorrect. Please check client param or contact us
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
errors:
type: string
examples:
Payment gateway error:
value:
errors: Invalid Customer Key
transaction_token not valid:
value:
errors: Invalid Payment token
User not authenticated:
value:
errors: Unauthenticated User
Invalid zip code:
value:
errors: Invalid Zip Code value
Missing zip code:
value:
errors: Zip Code required for this card type (Amex)
Invalid country:
value:
errors: Invalid country error
Payment adapter not supported:
value:
errors: This payment adapter is currently not supported or you might have passed the
incorrect payment adapter.
x-stoplight:
id: 86d781cf0d5d7
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
transaction_token:
type: string
description: Unique digital identifier/token of the user's payment card provided by
the payment processor
adapter_code:
type: string
description: Name of the payment processor / payment gateway. Valid value is par_payment.
preferred:
type: boolean
description: This value determines whether this card will be selected as the default
card or not when the user makes a payment through the mobile application. If the value
is set to true, this card will be selected as the default card for payments. Valid
values are true or false.
nickname:
type: string
description: Payment card nickname, as set by the user
billing_info:
type: object
description: Billing information of the cardholder
properties:
name:
type: string
description: Cardholder name.
country:
type: string
description: Country as specified by the cardholder in the billing address. Valid
values are USA and CAN.
zip_code:
type: string
description: Zip code as specified by the cardholder in the billing address. Required
when the card to be added is of type Amex.
required:
- client
- transaction_token
- adapter_code
examples:
default:
value:
client: <CLIENT_ID_GOES_HERE>
transaction_token: <TRANSACTION_TOKEN_GOES_HERE>
adapter_code: <ADAPTER_CODE_GOES_HERE>
preferred: true
nickname: NICKNAME_GOES_HERE
billing_info:
name: CUSTOMER_NAME_GOES_HERE
country: USA
zip_code: ZIP_CODE_GOES_HERE
parameters: []
get:
summary: Fetch All Saved Payment Cards
operationId: get-api2-mobile-payment_cards
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: array
description: Array of payment cards in the user’s account, if available
items:
type: object
properties:
uuid:
# --- truncated at 32 KB (786 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-mobile-api-openapi.yml