{ "opencollection": "1.0.0", "info": { "name": "POS API", "version": "1.0" }, "items": [ { "info": { "name": "Point Of Sale", "type": "folder" }, "items": [ { "info": { "name": "Location Configuration", "type": "http" }, "http": { "method": "GET", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/locations/configuration", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Accept-Language", "value": "" } ] }, "docs": "Get the configuration for a location using a unique API key (i.e., location key).\n\nThis API call requires the API key as well as the business key to be sent in the HTTP Authorization header in the following format:\n\nAuthorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE\n\nwhere \n\nLOCATION_KEY_GOES_HERE is the API key (which is unique for a location) and BUSINESS_KEY_GOES_HERE is the business key (which is unique for a business). \n\nSee cURL examples for more details.\n" }, { "info": { "name": "Program Meta", "type": "http" }, "http": { "method": "GET", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/meta", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Accept-Language", "value": "" } ] }, "docs": "Get information about business-level data, such as program type, platform configurations, list of redeemables (in case of points unlock redeemable program), etc.\n\n>Any update made to the configuration in the platform will be reflected in the response after 15 minutes, instead of in real time, in order to improve the response time.\n" }, { "info": { "name": "Create New User", "type": "http" }, "http": { "method": "POST", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users", "headers": [ { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "This API creates a new user account by using phone or email or card (at least one of them).\n" }, { "info": { "name": "User Look-up and Fetch Balance", "type": "http" }, "http": { "method": "GET", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/search", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Accept-Language", "value": "" } ], "params": [ { "name": "email", "value": "", "type": "query", "description": "Email address of the user." }, { "name": "phone", "value": "", "type": "query", "description": "Phone number of the user." }, { "name": "card_number", "value": "", "type": "query", "description": "Physical loyalty card generated by Punchh." }, { "name": "user_as_qrcode", "value": "", "type": "query", "description": "QR code of the user." }, { "name": "single_scan_code", "value": "", "type": "query", "description": "Single scan code of the user to be used in single scan flow. " }, { "name": "redemption_code", "value": "", "type": "query", "description": "Redemption code of the user as generated on the app or web." }, { "name": "reward_id", "value": "", "type": "query", "description": "ID of the user’s reward as generated on the app or web." }, { "name": "apple_nfc_data", "value": "", "type": "query", "description": "User identifier that enables look-up of user information generated from the Apple Pass. See [Implement Apple Pass Integration With POS](/docs/dev-portal-pos/ea3c77d831261-implement-apple-pass-integration-with-pos)" }, { "name": "nfc_token", "value": "", "type": "query", "description": "User identifier that enables the look-up of user information generated from the Google Pass. See [Implement Google Pass Integration With POS](/docs/dev-portal-pos/additional-topics/implement-google-pass-integration-with-pos)" }, { "name": "drive_thru_code", "value": "", "type": "query", "description": "4-digit numeric/alphanumeric drive-thru short code generated by the user from the brand's mobile app that enables lookup of user details and balance. The short code is mapped to the user ID. See [Generate a Drive-Thru Short Code](https://developers.partech.com/docs/dev-portal-mobile/647b28e02d630-generate-a-drive-thru-short-code).\n\nWhen the short code passed in the API is enabled for payments, Punchh uses the short code and the user ID mapped to it to retrieve the associated single scan code. Punchh then uses the single scan code to look up the user and returns it in the response, along with any rewards and payment information selected when the short code was generated.\n\nThe POS can use the single_scan_code for check-in, redemptions, and payments. See [Generate Single Scan Code API](https://developers.partech.com/docs/dev-portal-mobile/apis/mobile-api/tag/single-scan-code/post/api2/mobile/single_scan_tokens).\n\nThe API returns a 404 or 410 status code with the error message \"CODE_EXPIRED\" for an expired short code, and a 404 status code with the error message \"CODE_NOT_FOUND\" for an invalid or unmapped short code.\n" } ] }, "docs": "This API looks up a loyalty guest using an identifier to retrieve guest data and to assign the user to the check or transaction.\n\n## Fields Used for User Look-up\n\nThe following table summarizes the different look-up fields that are used in the request of this API endpoint. The POS makes a call using ***one*** of these identifiers (e.g., email address, phone number, QR code, or loyalty card number) to look up the loyalty user on the Punchh platform. **Sending one of the query parameters (see belo" }, { "info": { "name": "Create Check-in", "type": "http" }, "http": { "method": "POST", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/checkins", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Accept-Language", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a check-in for a customer.\n" }, { "info": { "name": "Store Receipt Details From POS", "type": "http" }, "http": { "method": "POST", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/receipt_details", "headers": [ { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "This API call requires the API key as well as the business key to be sent in the HTTP Authorization header in the following format:\n\nAuthorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE\n\nwhere \n\nLOCATION_KEY_GOES_HERE is the API key (which is unique for a location) and BUSINESS_KEY_GOES_HERE is the business key (which is unique for a business). \n\nSee cURL examples for more details. \n\n1\\. The receipt_details endpoint can store the same receipt multiple times. If the " }, { "info": { "name": "Create Transaction", "type": "http" }, "http": { "method": "POST", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/transactions", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Accept-Language", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Use the Create Transaction API to create a transaction for a customer (provided this functionality is enabled for the business by Punchh). The transaction registers the visit of the customer at a certain store, but the customer will not earn loyalty (points, etc.). One of the identifiers (`email`, `phone`, `card_number`, `user_as_qrcode`, `single_scan_token` or `redemption_code`) must be provided along with `location_key`." }, { "info": { "name": "Fetch Account Balance", "type": "http" }, "http": { "method": "GET", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/users/balance", "headers": [ { "name": "Authorization", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "The API fetches the account balance details of the user based on the program type of the business and different subscriptions if purchased by the user along with their benefits and discounts. \n\nNote: \n\n1\\. The `net_balance`, `points_balance`, `net_debits`, `pending_points`, `total_credits`, `total_debits`, and `total_points_credits` parameters are applicable if the program type is Points unlock redeemables. \n\n2\\. The `total_redeemable_visits`, `total_visits`, and `unredeemed_cards` parameters a" } ] }, { "info": { "name": "Payments", "type": "folder" }, "items": [ { "info": { "name": "Create Payment", "type": "http" }, "http": { "method": "POST", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/payments", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Content-Type", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "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 obtain" }, { "info": { "name": "Update Payment Status", "type": "http" }, "http": { "method": "PUT", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/payments", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Content-type", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "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" }, { "info": { "name": "Void/Cancel Payment", "type": "http" }, "http": { "method": "DELETE", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/payments", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Content/type", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "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** > **[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 a" }, { "info": { "name": "Get Payment Status", "type": "http" }, "http": { "method": "GET", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/payments/status", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Content-Type", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "The Get Payment Status API retrieves the correct status and response message to know how to handle the next step (e.g., success--apply payment, cancel--payment cancelled by user, etc.). \n\nFor more information, see: [Getting Payment Status](/docs/dev-portal-pos/fc53c158c75c6-pos-payments#getting-payment-status)\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** > **L" }, { "info": { "name": "Refund Payment", "type": "http" }, "http": { "method": "POST", "url": "https://SERVER_NAME_GOES_HERE.punchh.com/api/pos/payments/refund", "headers": [ { "name": "Authorization", "value": "" }, { "name": "Content-type", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "After an accepted/processed payment, you can use the Refund Payments API to refund the payment. \n\nFor more information, see [Refunding Payment](/docs/dev-portal-pos/additional-topics/pos-payments#refunding-payment)\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\n#### `btoken`\nThe API key for the business, located in the Punchh platform. Note: " } ] } ], "bundled": true }