Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/punchh-payments-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Punchh Payments API
version: '1.0'
contact:
name: Punchh Dev Support
url: https://developers.punchh.com
description: 'Operations tagged Payments across 2 of this provider''s published API definitions: punchh-mobile-api-openapi.yml, punchh-pos-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Payments
paths:
/api2/mobile/secure_tokens/{service}:
parameters:
- schema:
type: string
name: service
in: path
required: true
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: A user-based token that can be used for different services, such as gift cards, online ordering, etc.
examples:
default:
value:
token: TOKEN_GOES_HERE
summary: Fetch Client Token
description: 'Returns a secure client token that can be used for different services, such as gift cards, online ordering, etc. '
operationId: mobile_fetch_client_token
tags:
- Payments
parameters:
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Authorization'
- schema:
type: string
in: path
name: service
required: true
description: The service for which the secure token will be generated (e.g., ordering, braintree)
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: f51140e63501c
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
examples:
default:
value:
client: CLIENT_GOES_HERE
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
/api2/mobile/payments/client_token:
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: Payment client token
examples:
default:
value:
token: TOKEN_GOES_HERE
summary: Get Client Token
x-private: true
operationId: mobile_get_client_token
tags:
- Payments
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: 7053c182bee30
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
x-stoplight:
id: u1054amgmgwza
description: OAuth client ID provided by the business
payment_gateway_name:
type: string
x-stoplight:
id: yi9tccf8jxllq
description: Name of the payment gateway for which the nonce is generated. Currently, only "braintree" is supported.
enum:
- braintree
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
payment_gateway_name: braintree
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
/api2/mobile/payments:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties: {}
'401':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
message:
type: string
code:
type: integer
examples:
default:
value:
errors:
message: Access is denied due to invalid credentials.
code: 401
summary: Record Payment
x-private: true
operationId: mobile_record_payment
tags:
- Payments
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: 07db12035980f
requestBody:
content:
application/json:
schema:
type: object
properties:
payment_method_nonce:
type: string
description: Payment method nonce
membership_program_id:
type: string
description: Membership program ID
examples:
default:
value:
payment_method_nonce: PAYMENT_METHOD_NONCE_GOES_HERE
membership_program_id: MEMBERSHIP_PROGRAM_ID_GOES_HERE
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
/api2/mobile/iframe_payments/new:
get:
summary: Get a PAR Pay Token
tags:
- Payments
operationId: get-api2-mobile-iframe_payments-new
description: 'Enables a user to generate a token for a payment card. The user can use the PAR Pay token to purchase gift cards, reload gift cards, generate a single scan code, etc. The API response presents a web page showing fields for entering payment card details. Once this HTML is submitted with proper card details, it will return a token.
To generate a token, PAR Payments must be configured in the Punchh platform for the business to enable integration services. Once integration services are enabled, the platform can be configured to enable recurring payments for the payment processor. Contact your Punchh representative to update this Punchh platform configuration. <!--Cockpit > Dashboard > Miscellaneous Config > Enable Integration Services?--><!--Whitelabel > Integration Services-->'
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/User-Agent'
responses:
'200':
description: The response body will contain HTML text.
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
Payment not supported:
value:
error: Payment is not supported or invalid configuration
'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:
default:
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:
default:
value:
errors:
unknown_client:
- Client ID is incorrect. Please check client param or contact us
x-stoplight:
id: 210d5819985a4
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: OAuth client ID provided by the business
required:
- client
examples:
default:
value:
client: BUSINESS_CLIENT_ID_GOES_HERE
description: ''
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
/api/pos/payments:
post:
responses:
'200':
description: 'Successful response
'
content:
application/json:
schema:
type: object
properties:
first_name:
type: string
description: 'First name of the user
'
last_name:
type: string
description: 'Last name of the user
'
transaction_no:
type: string
description: "Unique identifier for the transaction request \n"
payment_reference_id:
type: string
description: 'Payment reference identifier from the payment processor
'
status:
type: string
description: "* processing - Intermediate status while processing payment (e.g., when the user approves payment)\n* unable_to_process - Failure with payment on the provider side \n* success - Payment success"
payment_type:
type: string
description: 'Payment type used for the single scan flow transaction (e.g., CreditCard, recurring, etc.). See [Single Scan Flow](/docs/dev-portal-pos/54e5a71a7205c-single-scan-flow)
'
payment_transaction_id:
type: string
description: Transaction ID provided by the provider. This should be printed by the POS on receipts for user reference.
response_message:
type: string
description: '* CREATED
* COMPLETED
'
created_at:
type: string
description: 'Date/time in ISO 8601 format
'
updated_at:
type: string
description: 'Date/time in ISO 8601 format
'
card_type:
type: string
x-stoplight:
id: 5ed838suvtt99
description: 'Payment card type as received from the payment service provider when PAR Pay is the payment service provider of the business. For other payment service providers, this parameter returns a null value. Possible values:
VIC - Visa
MCC - Mastercard
AXC - American Express Credit Card (AMEX)
DCC - Diners Club Credit Card
NVC - Discover Credit Card
JCB Card - JCB Card
GCC - Gift Card'
examples:
default:
value:
first_name: FIRST_NAME_GOES_HERE
last_name: LAST_NAME_GOES_HERE
transaction_no: '5678'
payment_reference_id: '1562'
status: Processing
payment_type: CreditCard
payment_transaction_id: TRANSACTION_ID_GOES_HERE
response_message: CREATED
created_at: '2021-05-01T12:00:00.000Z'
updated_at: '2021-05-01T12:00:00.000Z'
card_type: VIC
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
default:
value:
error: Invalid Location Key
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
default:
value:
error: User not found
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
default:
value:
error: Invalid payment type
tags:
- Payments
summary: Create Payment
description: "The Create Payment API commits the payment via the PAR Payment Services Gateway.\n\nFor more information, see: [Creating Payment](/docs/dev-portal-pos/fc53c158c75c6-pos-payments#creating-payments)\n\n### Headers\n\n#### `Token token`\nThe Location API key from the Punchh platform located under **Store Locations** > **All Store Locations** > **[Choose your location]** > **POS tab** > **Location key**\n#### `btoken`\nThe API key for the business, located in the Punchh platform. **Note:** This can be obtained only from Punchh administrators (e.g., Customer Success Manager). \n\n_For assistance with any API keys, reach out to your Punchh Customer Success Manager (CSM) or Implementation Manager (if applicable)._\n"
operationId: pos_create_payment_ssf
parameters:
- schema:
type: string
default: Token token="LOCATION_KEY_GOES_HERE" btoken="BUSINESS_KEY_GOES_HERE"
in: header
name: Authorization
description: '**Token token** Location API key from the Punchh platform. **btoken** Business API key from the Punchh platform.'
- schema:
type: string
default: application/json
in: header
name: Content-Type
description: Set to **application/json**
x-stoplight:
id: 41617c28303e8
requestBody:
content:
application/json:
schema:
type: object
properties:
payment_type:
type: string
description: 'Enter one of the following values for the Punchh single scan flow payment:
* Credit Card = CreditCard
* Recurring = recurring
See [Single Scan Flow](/docs/dev-portal-pos/54e5a71a7205c-single-scan-flow)'
single_scan_code:
type: string
description: Single scan code of the user is a required parameter when the user makes a payment through the single scan flow. The single scan code identifies the user making the payment.
payable:
type: integer
description: 'Total amount the customer paid after taxes, service charges, and discounts
'
pos_type:
type: string
description: 'Name of the POS system
'
pos_version:
type: string
description: 'Version number of the POS system
'
cc_last4:
type: string
description: 'Last 4 digits of the user''s credit card number
'
employee_id:
type: string
description: 'POS employee ID
'
employee_name:
type: string
description: 'POS employee name
'
revenue_id:
type: string
description: "ID of the POS function that designates order fulfillment. \nAlso known as order mode or order type (e.g., dine in, take out)\n\nNot be to confused with revenue center (e.g., bar, patio, dining room)\n"
revenue_code:
type: string
description: "Name of the POS function that designates order fulfillment. \nAlso known as order mode or order type (e.g., dine in, take out)\n\nNot be to confused with revenue center (e.g., bar, patio, dining room)\n"
amount:
type: number
description: 'Receipt amount excluding taxes and inclusive of discounts
'
subtotal_amount:
type: number
description: 'Receipt amount excluding taxes and inclusive of discounts
'
currency_code:
type: string
description: 'Code of the currency in ISO 4217 format
'
receipt_datetime:
type: string
description: 'Date/time when the check was opened in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
'
punchh_key:
type: string
description: 'Value of the [Punchh QR code or Punchh barcode](/docs/dev-portal-pos/33262bfade37e-implement-the-punchh-barcode-algorithm) '
transaction_no:
type: string
description: "Unique identifier for the transaction request. Regardless of success or failure, only one transaction number per request. This is NOT to be confused with the POS check number. \n"
menu_items:
$ref: '#/components/schemas/menu_items'
required:
- payment_type
- single_scan_code
- payable
- pos_type
- pos_version
- amount
- subtotal_amount
- currency_code
- receipt_datetime
- punchh_key
- transaction_no
- menu_items
examples:
Payment via SSF Flow QR Code:
value:
payment_type: CreditCard
single_scan_code: SINGLE_SCAN_CODE_GOES_HERE
payable: 46
pos_type: Aloha
pos_version: v1.0
cc_last4: ''
employee_id: '01'
employee_name: EMPLOYEE_NAME_GOES_HERE
revenue_id: '111'
revenue_code: CODE_GOES_HERE
amount: 12.72
subtotal_amount: 12.72
currency_code: USD
receipt_datetime: '2020-02-25T20:10:45+05:30'
punchh_key: PUNCHH_KEY_GOES_HERE
transaction_no: '3387553'
menu_items:
- item_name: White rice
item_qty: 1
item_amount: 2.86
menu_item_type: M
menu_item_id: '3419'
menu_family: '800'
menu_major_group: '152'
- item_name: Brown rice
item_qty: 1
item_amount: 7.86
menu_item_type: M
menu_item_id: '3418'
menu_family: '800'
menu_major_group: '152'
description: ''
put:
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
first_name:
type: string
description: First name of the user
last_name:
type: string
description: Last name of the user
transaction_no:
type: string
description: Unique identifier for the transaction request
payment_reference_id:
type: string
description: Payment reference identifier from the payment processor
status:
type: string
description: 'Punchh payment processing status. Possible values:
* processing: An intermediate status indicating that the payment is being processed (e.g., when the user approves the payment)
* processed: Indicates that the POS has sent the payment status as complete, and the system has marked the payment as processed
* unable_to_process: Indicates a failure in processing the payment on the provider''s side
* success: Indicates that the payment was successfully completed
* unable_to_refund: Indicates that the system was unable to refund the payment
* refunded: Indicates that the payment has been successfully refunded
* refunding: An intermediate status between success/unused and refunded/not refunded'
response_message:
type: string
description: Status as returned by the provider for payments
payment_type:
type: string
description: Payment type used for the single scan flow transaction (e.g., CreditCard, recurring, etc.). See [Single Scan Flow](/docs/dev-portal-pos/54e5a71a7205c-single-scan-flow)
created_at:
type: string
description: Date/time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
card_type:
type: string
x-stoplight:
id: 1asbbrfv1egzb
description: 'Payment card type as received from the payment service provider when PAR Pay is the payment service provider of the business. For other payment service providers, this parameter returns a null value. Possible values:
VIC - Visa
MCC - Mastercard
AXC - American Express Credit Card (AMEX)
DCC - Diners Club Credit Card
NVC - Discover Credit Card
JCB Card - JCB Card
GCC - Gift Card'
examples:
default:
value:
first_name: FIRST_NAME_GOES_HERE
last_name: LAST_NAME_GOES_HERE
transaction_no: 352083094-10040
payment_reference_id: '14000'
status: processed
response_message: COMPLETED
payment_type: CreditCard
created_at: '2020-12-18T07:05:11Z'
card_type: VIC
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
default:
value:
error: Invalid Location Key
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
default:
value:
error: User not found
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
error:
type: string
examples:
default:
value:
error: Invalid payment type
description: "The Update Payment Status API updates the payment status in the Punchh platform after the POS marks the payment as complete. \n\nFor more information, see: [Updating Payment Status](/docs/dev-portal-pos/fc53c158c75c6-pos-payments#updating-payments)\n\n### Headers\n\n#### `Token token` \nThe Location API key from the Punchh platform located under **Store Locations** > **All Store Locations** > **[Choose your location]** > **POS tab** > **Location key**\n#### `btoken`\nThe API key for the business, located in the Punchh platform. **Note:** This can be obtained only from Punchh administrators (e.g., Customer Success Manager). \n\n_For assistance with any API keys, reach out to your Punchh Customer Success Manager (CSM) or Implementation Manager (if applicable)._\n"
summary: Update Payment Status
operationId: pos_update_payments
tags:
- Payments
parameters:
- schema:
type: string
default: Token token="LOCATION_KEY_GOES_HERE" btoken="BUSINESS_KEY_GOES_HERE"
in: header
name: Authorization
description: '**Token token** Location API key from the Punchh platform. **btoken** Business API key from the Punchh platform.'
- schema:
type: string
default: application/json
in: header
name: Content-type
description: Set to **aplication/json**
x-stoplight:
id: 61f48ba9babb2
requestBody:
content:
application/json:
schema:
type: object
properties:
payment_reference_id:
type: string
x-stoplight:
id: 42dfle71x6g2a
description: Payment reference identifier from the payment processor. This is obtained from the response of the [Create Payment API](/docs/dev-portal-pos/b3A6NTAyODM5Mjg-create-a-payment).
payment_type:
type: string
description: "Enter one of the following values for the Punchh single scan flow payment: \n* Credit Card = CreditCard\n* Recurring = recurring\nSee [Single Scan Flow](/docs/dev-portal-pos/54e5a71a7205c-single-scan-flow)"
email:
type: string
description: Email address of the user. Required for loyalty guests. In the case of single scan flow, email is not a required parameter.
status:
type: string
description: Send "completed" to update the payment status and finalize payment processing. Use the [Get Payment Status](/docs/dev-portal-pos/63dd6a196a566-get-payment-status) endpoint to obtain the current status and status updates.
single_scan_code:
type: string
description: Single scan code of the user is a required parameter when the user makes a payment through the single scan flow. The single scan code identifies the user making the payment.
required:
- payment_type
- email
- status
examples:
Example:
value:
payment_type: CreditCard
email: test@example.com
status: completed
single_scan_code: SINGLE_SCAN_CODE_GOES_HERE
delete:
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
first_name:
type: string
description: First name of the user
last_name:
type: string
description: Last name of the user
transaction_no:
type: string
description: Unique identifier for the transaction request
payment_reference_id:
type: string
description: Payment reference identifier from the payment processor
status:
type: string
description: 'Punchh status returned as: processing, processed, unable_to_process, success, unable_to_refund, refunded, refunding'
response_message:
type: string
description: 'Status returned by the provider for payments as: AWAITING_USER_INPUT, SUCCESS, ABORTED, FAILED, CANCELLED, CREATED, COMPLETED
'
payment_type:
type: string
description: Payment type used for the single scan flow transaction (e.g., CreditCard, recurring, etc.). See [Single Scan Flow](/docs/dev-portal-pos/54e5a71a7205c-single-scan-flow)
created_at:
type: string
description: Date/time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
updated_at:
type: string
description: Date/time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
payment_transaction_id:
type: string
description: Transaction ID provided by the provider. This should be printed by the POS on receipts for user reference.
card_type:
type: string
x-stoplight:
id: qft5xmuo5royq
description: 'Payment card type as received from the payment service provider when PAR Pay is the payment service provider of the business. For other payment service providers, this parameter returns a null value. Possible values:
VIC - Visa
MCC - Mastercard
AXC - American Express Credit Card (AMEX)
DCC - Diners Club Credit Card
NVC - Discover Credit Card
JCB Card - JCB Card
GCC - Gift Card'
examples:
Example:
value:
- first_name: FIRST_NAME_GOES_HERE
last_name: LAST_NAME_GOES_HERE
transaction_no: 352083094-10040
payment_reference_id: '14000'
status: unable_to_process
response_message: CANCELLED
payment_type: CreditCard
created_at: '2020-12-18T07:05:11Z'
card_type: VIC
summary: Void/Cancel Payment
operationId: pos_void_payments
tags:
- Payments
description: "The Void/Cancel Payments API voids the payment request. \n\nFor more information, see: [Voiding Payments](/docs/dev-portal-pos/additional-topics/pos-payments#voiding-payment)\n\n### Headers\n\n#### `Token token`\nThe Location API key from the Punchh platform located under **Store Locations** > **All Store Locations** >
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-payments-api-openapi.yml