PAR Pay
PAR Pay is the payment processor for PAR Ordering, and the one new integrations are configured with. It takes cards, Apple Pay, Google Pay and gift cards through a single processor.
The flow itself is not PAR Pay specific — Make a Payment describes it, and it is the same for every processor. This page only covers what PAR Pay puts into that flow: what appears in additional_info, which actions you get, and what you have to send back when you create the order.
You will see PAR Pay under these payment_processor_type_id values:
| ID | What it is |
|---|---|
| 38 | PAR Pay — cards, Apple Pay, Google Pay and gift cards, all on one processor. This is what new brands report, and what the rest of this page describes |
| 32 | Aurus — the earlier PAR Pay integration for cards and wallets. Brands onboarded before PAR Pay 38 still report it |
| 35 | Aurus Gift Card — the gift card processor configured alongside 32 on those brands |
Branch on the payment_processor_type_id you get back from payment initialization, not on which processor you expect the brand to have. The contracts differ: 38 hands you an iframe URL in additional_info, 32 sends you through a redirect action, and the wallet payloads are shaped differently. Everything for 32 and 35 is in Aurus: the earlier PAR Pay integration at the end of this page.
What a payment initialization looks like
Everything below is the response to POST /api/cart/{cart_id}/payments/init when payment_processor_type_id is 38. The envelope is always the same; only the last two fields vary.
| Scenario | additional_info |
actions |
|---|---|---|
| Saved card, saved gift card | null |
none |
| New card | iframeUrl |
none |
| Apple Pay | merchant_id, amount, currency, country |
auth |
| Google Pay | Google Pay gateway configuration and merchant identifiers | none |
| New gift card | bin_ranges |
none |
For a saved card there is nothing for your client to do. Initialize, then create the order with the hash.
New card
The customer is paying with a card they have not saved, so the card details have to be collected by PAR Pay rather than by you.
{
"payment_init_hash": "032878b199f90e13e1bdce036e00f157",
"payment_processor_type_id": 38,
"amount": 1094,
"expires_in": 1799,
"additional_info": {
"iframeUrl": "https://parpay.example.com/iframe?session=a0f3c1e9-5b7d-4e2a-9c61-3f8d2b7a6e10"
}
}
There is no action to follow. additional_info.iframeUrl is the PAR Pay hosted card form; load it in an iframe or a WebView exactly as given — it carries a session that cannot be regenerated on your side, and it is valid for this initialization only.
When the customer submits the form, the page posts a message event to the window that embeds it. Listen for it with window.addEventListener("message", …); the message is an object, not a string:
{
"type": "transaction:success",
"data": {
"paymentMethodData": {
"one_time_token": "30910032626134340597000708770932",
"billing_zip_code": "60601"
}
}
}
| Message | Meaning |
|---|---|
type: "transaction:success" |
The card was tokenized. Read data.paymentMethodData.one_time_token, and data.paymentMethodData.billing_zip_code when the form collected a ZIP code |
type: "transaction:failure" |
Tokenization failed. Let the customer try again, or pick another method |
Ignore messages whose type is anything else, and check event.origin against the host of iframeUrl before you trust one. There is no success or fail redirect: the form never navigates away, so in a native WebView you bridge the postMessage to your app instead of watching the URL. The PAR hybrid apps do exactly that — they are the web app running in a WebView, and read the same message.
Send the token as payment_info.one_time_token when you create the order, together with payment_info.billing_zip_code when you received one. The token is single-use and tied to this initialization; if the customer changes the cart and you check out again, initialize again and load a fresh form.
Paying with a new card does not save it. If the customer wants the card kept for next time, run the Store Payment Method flow — the hosted form and the token are the same, only the call you post them to differs.
Apple Pay
{
"payment_init_hash": "032878b199f90e13e1bdce036e00f157",
"payment_processor_type_id": 38,
"amount": 1094,
"additional_info": {
"merchant_id": "merchant.com.example.brand",
"amount": 10.94,
"currency": "USD",
"country": "US"
},
"actions": [
{
"type": "auth",
"url": "https://api-public-demo.menu.app/api/payment-processors/auth-payment?mt_application_id=137&mt_payment_processor_id=56",
"method": "POST"
}
]
}
| Attribute | Type | Description |
|---|---|---|
merchant_id |
string | The Apple Pay merchant identifier to open the payment sheet with |
amount |
number | The amount in major units, for display in the sheet |
currency |
string | ISO currency code |
country |
string | ISO country code of the store |
Open the Apple Pay sheet with these values. Apple then asks you to validate the merchant, which is what the auth action is for — post the validation URL to it as described in Make a Payment, together with auth_info.initiative_context, the domain registered with Apple for this merchant identifier. Hand the returned session_object to completeMerchantValidation().
The auth action exists for this web-style merchant validation. A hybrid app whose Apple Pay plugin surfaces the same event with a validation URL makes the same two calls; initiative_context must still be the https domain registered with Apple, not an app scheme — the PAR hybrid apps replace their capacitor:// host with https:// before sending it. A native PassKit integration that validates the merchant with its own merchant identity certificate never receives a validation URL and does not call the auth action; it goes from the initialization straight to order creation with the payment token.
Once the customer confirms, create the order with the Apple PaymentToken object you received — paymentData, paymentMethod and transactionIdentifier, unchanged — under payment_info.additional_info.wallet_pay.applePay:
{
"payment_info": {
"payment_init_hash": "032878b199f90e13e1bdce036e00f157",
"additional_info": {
"wallet_pay": {
"applePay": {
"paymentData": { "version": "EC_v1", "data": "…", "signature": "…", "header": { "…": "…" } },
"paymentMethod": { "displayName": "Visa 1234", "network": "Visa", "type": "debit" },
"transactionIdentifier": "A1B2C3…"
}
}
}
}
}
PAR Ordering passes it to PAR Pay as the payment; you do not call PAR Pay yourself.
Google Pay
{
"payment_init_hash": "9d8416985b57de4b93d87f7f88ef11da",
"payment_processor_type_id": 38,
"amount": 1094,
"additional_info": {
"paymentProvider": "aurus",
"gatewayMerchantId": "67890852",
"status": "Success",
"statusMessage": "Google Pay configuration success",
"google_merchant_id": "12345678901234567890",
"google_merchant_name": "Example Brand",
"amount": 10.94,
"currency": "USD",
"country": "US"
}
}
There is no action to follow: open the Google Pay sheet with these values directly.
| Attribute | Type | Description |
|---|---|---|
paymentProvider |
string | The gateway PAR Pay uses for Google Pay. Currently aurus |
gatewayMerchantId |
string | The merchant identifier to pass in the Google Pay tokenization specification |
status, statusMessage |
string | Result of fetching the configuration from PAR Pay. Anything other than Success means the sheet should not be offered |
google_merchant_id |
string | Your Google Pay Business Console merchant id, for merchantInfo |
google_merchant_name |
string | The merchant name to show in the sheet |
amount, currency, country |
The transaction values, as for Apple Pay |
Build the card payment method with a PAYMENT_GATEWAY tokenization specification whose gateway is auruspay and whose gatewayMerchantId is the value above:
{
"type": "CARD",
"parameters": { "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"], "allowedCardNetworks": ["AMEX", "DISCOVER", "MASTERCARD", "VISA"] },
"tokenizationSpecification": {
"type": "PAYMENT_GATEWAY",
"parameters": { "gateway": "auruspay", "gatewayMerchantId": "67890852" }
}
}
When the sheet resolves, paymentData.paymentMethodData.tokenizationData.token is a JSON string. Parse it and send the resulting object — signature, intermediateSigningKey, protocolVersion, signedMessage — under payment_info.additional_info.wallet_pay.googlePay when you create the order:
{
"payment_info": {
"payment_init_hash": "9d8416985b57de4b93d87f7f88ef11da",
"additional_info": {
"wallet_pay": {
"googlePay": {
"signature": "MEUCIQ…",
"intermediateSigningKey": { "signedKey": "{\"keyValue\":\"…\",\"keyExpiration\":\"…\"}", "signatures": ["MEQCIB…"] },
"protocolVersion": "ECv2",
"signedMessage": "{\"encryptedMessage\":\"…\",\"ephemeralPublicKey\":\"…\",\"tag\":\"…\"}"
}
}
}
}
}
Gift cards
Gift cards run on the same processor as cards — there is no separate gift card processor on a PAR Pay 38 brand, and payment_processor_type_id is 38 for them too. A gift card the customer has not saved is validated against BIN ranges rather than a hosted form, because gift card numbers are not PCI-regulated and can be posted to us directly.
{
"payment_init_hash": "9d8416985b57de4b93d87f7f88ef11da",
"payment_processor_type_id": 38,
"amount": 1094,
"additional_info": {
"bin_ranges": [
{ "range": { "from": "7000", "to": "9999" }, "pin_required": false, "refundable": true, "rechargeable": true },
{ "range": { "from": "8307", "to": "9000" }, "pin_required": true, "refundable": true, "rechargeable": true },
{ "range": { "from": "200", "to": "10001" }, "pin_required": false, "refundable": false, "rechargeable": false }
]
}
}
Each range describes a rule for the cards whose leading digits fall inside it. The lower bound is at least three digits and there is no upper bound; the ranges are configured per brand.
Ranges can overlap, and a card can match several. In practice that means: if any matching range has pin_required: true, prompt for the PIN. refundable and rechargeable tell you whether to offer a refund back to the card and whether to offer a reload.
Before charging it, you can confirm the card is valid with POST /customer-accounts/{customer_account_id}/gift-cards/check. It answers yes or no — it does not return a balance, and the card does not have to be saved first.
Create the order with payment_info.gift_card_number, plus payment_info.gift_card_code for the PIN where one is required. Before redeeming, PAR Ordering reads the card's balance; if it is lower than the amount you initialized, the order fails with a processor error whose message is GIFTCARD: Insufficient funds. The cart is intact, so show the balance and let the customer split the payment or pick another method.
A gift card rarely covers the whole cart, so this is the method most often used in a split payment.
Balances and reloads
Once a gift card is saved to the account you can show what is left on it and, where the brand allows, add funds:
| Call | What it gives you |
|---|---|
GET /customer-accounts/{customer_account_id}/gift-cards |
The saved gift cards, for a wallet screen. balance is null on every entry — it is not fetched for the list |
GET /customer-accounts/{customer_account_id}/gift-cards/{stored_payment_method_id} |
One card with its live balance in minor units, read from PAR Pay at the moment you call. Load it when the customer opens a card, not for every card in the list |
POST /customer-accounts/{customer_account_id}/gift-cards/{stored_payment_method_id}/reload |
Adds amount minor units to the card and returns it with the new balance. Offer it only when the card's BIN range says rechargeable |
The PAR web app shows balances this way and sends customers to the brand's own site to buy or reload cards, so a reload button in your app is optional.
What happens after the payment
A PAR Pay card or wallet payment is a single-step purchase: the money is taken when the order is created, and there is no separate capture. Gift cards are redeemed the same way. You do not have to do anything to settle.
Refunds and voids are issued from the Management Center, not by your client. The one thing your client can do is let the customer cancel inside the brand's cancellation window: POST /api/orders/{order_uuid}/cancel cancels the order and reverts its payment automatically — see Let the customer cancel. Either way, a card payment is voided or refunded depending on whether it has settled; a gift card payment is always refunded back to the card, because gift card redemptions cannot be voided.
Storing a PAR Pay payment method
Store Payment Method covers the full flow. Three things are worth knowing about PAR Pay specifically.
generate-tokens returns two entries for the one processor. Both report payment_processor_type_id: 38 and the same payment_processor_id; one carries additional_info.iframeUrl for a card and the other carries bin_ranges for a gift card. Follow the one that matches what the customer is saving. Neither has a token field — that belongs to the Aurus integration.
The properties you post back differ by card type. For a card, load iframeUrl as described under New card, take one_time_token from the transaction:success message and send it as the only property. For a gift card, send gift_card_number and, where its BIN range requires it, gift_card_code — a missing PIN is rejected with Gift card code is required.
Saving a card runs a zero-amount authorization. That is how PAR Pay validates the card and issues the vault token. The customer may see a temporary $0 authorization on their statement; nothing is charged.
Once stored, the card is used like any other saved method: initialize with stored_payment_method_id, get additional_info: null and no actions back, and create the order with just the hash.
Aurus: the earlier PAR Pay integration
Brands onboarded before PAR Pay 38 report 32 (Aurus) for cards and wallets and 35 (Aurus Gift Card) for gift cards. The flow is the same — initialize, follow what comes back, create the order — but what comes back is shaped differently. Everything in this section applies when payment_processor_type_id is 32 or 35.
| Scenario | additional_info |
actions |
|---|---|---|
| Saved card, saved gift card | null |
none |
| New card | null |
redirect |
| Apple Pay | merchant and session identifiers | auth |
| Google Pay | merchant and session identifiers | none |
New gift card (35) |
bin_ranges |
none |
New card on Aurus
{
"payment_init_hash": "032878b199f90e13e1bdce036e00f157",
"payment_processor_type_id": 32,
"amount": 1094,
"expires_in": 1799,
"additional_info": null,
"actions": [
{
"type": "redirect",
"url": "https://api-public-demo.menu.app/api/payment-processors/init_token?mt_application_id=683&mt_payment_processor_id=392&tokenType=1&template=card&isPayment=1&successUrl=…&failUrl=…&sessionId=309200223173329411640000363990&iframeUrl=https%3A%2F%2Fuatps48.aurusepay.com%2Fstoreservices%2Fecom%2Fgetiframe%3Fa%3D0369E34f1e9…"
}
]
}
The URL is a page hosted by PAR Ordering that embeds the Aurus card form. Load it in a WebView or iFrame exactly as given — it carries a session that cannot be regenerated on your side.
When the customer submits the form you get a one-time token back in one of two ways:
| Platform | How the token reaches you |
|---|---|
| Web | The page calls window.top.postMessage("one-time-token=…"), and separately "zipcode=…" if AVS is on |
| Mobile | The WebView is redirected to the success URL with ?one-time-token=… in the query string |
A failure redirects to the fail URL with ?error=123456-ErrorMessage instead. The success and fail URLs are the ones already embedded in the action URL; Aurus can be configured to use endpoints of your own instead.
Send the token as payment_info.one_time_token when you create the order, and the ZIP code as payment_info.billing_zip_code when you received one.
Apple Pay on Aurus
{
"payment_init_hash": "032878b199f90e13e1bdce036e00f157",
"payment_processor_type_id": 32,
"amount": 1094,
"additional_info": {
"merchant_id": "merchant.com.example.brand",
"sessionId": "306805926262550654066895041517",
"requestId": "82f86d9a-c772-42c6-9b92-f37438490b62",
"amount": "10.94",
"currency": "USD",
"country": "US"
},
"actions": [
{
"type": "auth",
"url": "https://api-public-demo.menu.app/api/payment-processors/auth-payment?mt_application_id=137&mt_payment_processor_id=56",
"method": "POST"
}
]
}
| Attribute | Type | Description |
|---|---|---|
merchant_id |
string | The Apple Pay merchant identifier to open the payment sheet with |
sessionId |
string | Aurus session for this payment |
requestId |
string | Aurus request identifier for this payment |
amount |
string | The amount as a decimal string, for display in the sheet |
currency |
string | ISO currency code |
country |
string | ISO country code of the store |
Open the Apple Pay sheet with these values and validate the merchant through the auth action exactly as for PAR Pay 38. Once the customer confirms, create the order with the Apple Pay payment data under payment_info.additional_info.get_session_token_request.
Google Pay on Aurus
{
"payment_init_hash": "9d8416985b57de4b93d87f7f88ef11da",
"payment_processor_type_id": 32,
"amount": 1094,
"additional_info": {
"merchant_id": "784302",
"gateway_merchant_id": "exampleGatewayMerchantId",
"google_merchant_id": "12345678901234567890",
"google_merchant_name": "Example Brand",
"sessionId": "309100223174408561380000384143",
"requestId": "0f6c2f8f-1f0c-4a2f-bb0e-6b0a3d4a1c22"
}
}
There is no action to follow: open the Google Pay sheet with these values directly. gateway_merchant_id is the Aurus identifier you pass in the Google Pay tokenization specification, with auruspay as the gateway; google_merchant_id and google_merchant_name are your Google Pay Business Console credentials.
Create the order with the Google Pay payment data under payment_info.additional_info.GetSessionTokenRequest, carrying the SessionId from additional_info and the parsed token as PaymentToken.
The wallet keys differ in case between the two Aurus wallets: Apple Pay is read from
get_session_token_requestand Google Pay fromGetSessionTokenRequest. This is a quirk of the Aurus integration, not a typo in this guide. PAR Pay38useswallet_pay.applePayandwallet_pay.googlePayfor both.
Gift cards on Aurus
Gift cards live on a separate processor, 35, configured alongside the card processor. The initialization carries bin_ranges exactly as described for PAR Pay 38 above, the check endpoint works the same way, and you create the order with payment_info.gift_card_number and, where required, payment_info.gift_card_code.
{
"payment_init_hash": "9d8416985b57de4b93d87f7f88ef11da",
"payment_processor_type_id": 35,
"amount": 1094,
"additional_info": {
"bin_ranges": [
{ "range": { "from": "7000", "to": "9999" }, "pin_required": false, "refundable": true, "rechargeable": true },
{ "range": { "from": "8307", "to": "9000" }, "pin_required": true, "refundable": true, "rechargeable": true }
]
}
}
Storing a payment method on Aurus
generate-tokens returns two processors, not one — the card processor (32) and the gift card processor (35) — and you have to follow the one that matches what the customer is saving. The card entry carries a token and a redirect action to the same hosted form described above; the gift card entry carries bin_ranges instead.
The properties you post back differ by card type. For a card, send the one_time_token from the hosted form together with the token from generate-tokens. For a gift card, send gift_card_number and, where required, gift_card_code, against the 35 processor's id.
