Store Payment Method
This guide shows how to let a customer save a payment method to their account, so they can pay with it later without entering it again.
Only credit cards and gift cards can be stored as a payment method to a customer account - other payment methods have flows that are initiated during checkout and require user interaction (e.g., Apple Pay / Google Pay where the user confirms their payment method when making the payment), and as such cannot be saved to a customer account.
Generate Tokens / URLs
Card details are collected by the processor's hosted form, embedded in an iframe or WebView — PAR Pay hands you the form URL directly, Aurus through a redirect action. Gift card numbers are the one thing you collect yourself.
Beware of PCI Compliance when posting card details directly to a payment processor
If your web application natively accepts full credit card PANs, or your infrastructure in any way touches full credit card PANs, you are subject to higher PCI compliance standards. Make sure you are familiar with PCI certification levels before proceeding - PAR Ordering takes no responsibility for PCI compliance of integrators.
Do not under any circumstances post full credit card PANs to the PAR Ordering APIs - full PANs are always to be posted directly to the payment processor, passed through the payment processor's SDK or entered into the payment processor web app.
For Gift Cards, PCI compliance requirements do not apply.
Start by asking for the tokens or URLs you need to capture the payment method, from /payment-processors/generate-tokens:
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
Authorization HTTP header |
string | "Bearer {customer_account_token}" |
JWT Token of Customer Account |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/payment-processors/generate-tokens",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json",
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvY3VzdG9tZXJzL3JlZnJlc2giLCJpYXQiOjE2OTEzMzA4NjUsImV4cCI6MTY5MTM3MjA1OCwibmJmIjoxNjkxMzY4NDU4LCJqdGkiOiJJT2IwQ0VteFNiZ21vTXlSIiwic2V0UmVmcmVzaFRUTCI6MjYyODAwMCwic3ViIjoiNTA5MDYzNyIsInBydiI6ImNjMzI5MjFhMTU0ODBhMTE3ZDliYmM3MmMwZTEyNTZhNjg1MjQ1OGIiLCJhcHBsaWNhdGlvbl9pZCI6MjAxNSwic2Vzc2lvbl9pZCI6MjY2MjF9.Y5zJQgx4j4fHrNebQoAn3bGtr_iHa6DSKfNjQfkvjvg"
}
}
Response
On a PAR Pay brand (payment_processor_type_id 38) you get two entries for the one processor — the same payment_processor_id twice. The first carries the hosted card form in additional_info.iframeUrl, the second the gift card bin_ranges. Follow the one that matches what the customer is saving.
{
"status": "OK",
"code": 200,
"data": {
"tokens": [
{
"payment_processor_id": "c2f3a1d4-7b8e-4c5f-9a0b-1d2e3f4a5b6c",
"payment_processor_type_id": 38,
"additional_info": {
"iframeUrl": "https://parpay.example.com/iframe?session=a0f3c1e9-5b7d-4e2a-9c61-3f8d2b7a6e10"
}
},
{
"payment_processor_id": "c2f3a1d4-7b8e-4c5f-9a0b-1d2e3f4a5b6c",
"payment_processor_type_id": 38,
"bin_ranges": [
{
"range": {
"to": "7500",
"from": "7000"
},
"refundable": false,
"pin_required": false,
"rechargeable": true
},
{
"range": {
"to": "4999",
"from": "4000"
},
"refundable": false,
"pin_required": true,
"rechargeable": false
}
]
}
]
}
}
On a brand still on Aurus you get two processors instead — the card processor (32) with a token and a redirect action to the hosted form, and the gift card processor (35) with bin_ranges:
{
"status": "OK",
"code": 200,
"data": {
"tokens": [
{
"payment_processor_id": "5bab16ce-bb27-4e62-aff4-124266647eaf",
"payment_processor_type_id": 32,
"token": "bc31e770-bbca-47bf-884b-27e2563a9033",
"actions": [
{
"type": "redirect",
"url": "https://api-public-demo.menu.app/api/payment-processors/init_token?mt_application_id=629dd551-821f-4d81-ad3d-c6c777e848e5&mt_payment_processor_id=5bab16ce-bb27-4e62-aff4-124266647eaf&tokenType=1&template=card&isPayment=0&successUrl=https%3A%2F%2Fapi-public-demo.menu.app%2Fapi%2Fpayment-processors%2Fsuccess%3Fmt_application_id%3D629dd551-821f-4d81-ad3d-c6c777e848e5%26_menu_oapi%3Dtrue%26_menu_reqid%3Da29daa5e-ccc0-4e96-aae7-8d889c108497&failUrl=https%3A%2F%2Fapi-public-demo.menu.app%2Fapi%2Fpayment-processors%2Ffail%3Fmt_application_id%3D629dd551-821f-4d81-ad3d-c6c777e848e5%26_menu_oapi%3Dtrue%26_menu_reqid%3Daf70d6ae-549d-4837-9307-c14f44c1757e&sessionId=309300423218747336940000100085&iframeUrl=https%3A%2F%2Fuatps48.aurusepay.com%2Fstoreservices%2Fecom%2Fgetiframe%3Fa%3D0369D4D7f1e9b6fe33a826efb184f6ecb618ef26582c0e1230febc98c8b2c6e3313e5e58ea96b27ca545ba2eada315a4ca74e7f296c8986242a2c547cf990b49d5ae6d86233913cca6b2d885a38243a50f27bcda84b3a44c2f5130551ef807137824dfca88cb7941d75c5818f2d926920539727e8581f67510d7c3625e3c27e1b2d796c789baf937b78cad120644c0a3d584b306e786b4821841b0a93dcc69c42290f9662d86ab452e2e09e0c7d66c51ab5333ca915df03d8a991e90cb0be695fc40859d99db4a7d03d656a0d1307847fdfda4aa2ccde314b0caca7a29f7ab0695dd5e8321e58309b85840708ec2e1d90f7515c801b9e609c6395decb1044765e2937cb2dd4fefc978f537833f263eb90120d14de5763b1279b2f20407ccd11c369095428675e3fd8364c82798f99446036e21c4b48b62f04eabdbd2ae7e9668348edf4ef0102af87ab8d15e67060cfbd8bc0147fb68a535fee9c70f65bf2001e30735d0e0dc700cea4ca00c8a552714c949b4ad558033c6b22dfff9e4b64f4894a133a5&_menu_oapi=true&_menu_reqid=c7869274-668b-489e-903e-c5802a859b67"
}
]
},
{
"payment_processor_id": "47490e87-ff1a-4cbf-93f3-c9aabbc9b7ca",
"payment_processor_type_id": 35,
"bin_ranges": [
{
"range": {
"to": "7500",
"from": "7000"
},
"refundable": false,
"pin_required": false,
"rechargeable": true
},
{
"range": {
"to": "4999",
"from": "4000"
},
"refundable": false,
"pin_required": true,
"rechargeable": false
}
]
}
]
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
tokens |
array[Tokens] | One entry per thing you can store. PAR Pay (38) returns two entries for the same processor, one for cards and one for gift cards; Aurus returns one entry per processor (32 and 35). Follow the entry that matches what the customer is saving |
|
tokens.[i].payment_processor_id |
string | "c2f3a1d4-7b8e-4c5f-9a0b-1d2e3f4a5b6c" |
Payment Processor UUID — send it back as payment_processors.[i].id when you store |
tokens.[i].payment_processor_type_id |
id | 38 |
Type ID of Payment Processor - see Payment Processors and Payment Methods reference |
tokens.[i].additional_info.iframeUrl |
string | "https://parpay.example.com/iframe?session=…" |
PAR Pay (38) only. The hosted card form; load it and read the transaction:success message as described in the PAR Pay guide |
tokens.[i].token |
string | "bc31e770-bbca-47bf-884b-27e2563a9033" |
Aurus (32) only. Post it back as properties.token together with the one-time token. PAR Pay entries have no token |
tokens.[i].actions.[i].type |
string | "redirect" |
Aurus (32) only. The action your client has to take to store the payment method with that processor |
tokens.[i].actions.[i].url |
string | "https://api-public-demo.menu.app/api/payment-processors/init_token" |
Aurus (32) only. The processor's hosted page that collects the card details. Open it as returned; do not build it yourself |
tokens.[i].bin_ranges |
array[bin_range] | Array of BIN ranges (set in the Management Center) that can have different properties and requirements. If any gift card numbers that fall into any of the returned BIN ranges have "tokens.[i].bin_ranges.[i].pin_required" set to "true" the user must be prompted to enter the PIN. | |
tokens.[i].bin_ranges.[i].range |
object | BIN range object containing from and to values. If BIN ranges overlap, and any of them have pin_required set to true the user must be prompted for PIN entry. |
|
tokens.[i].bin_ranges.[i].range.from |
string | "4000" |
The lower limit is 3 digits, there is no upper limit. (configurable in the Management Center) |
tokens.[i].bin_ranges.[i].range.to |
string | "4999" |
The lower limit is 3 digits, there is no upper limit. (configurable in the Management Center) |
tokens.[i].bin_ranges.[i].refundable |
bool | false |
Whether a transaction can get refunded back to a gift card |
tokens.[i].bin_ranges.[i].pin_required |
bool | true |
Whether the gift card needs a PIN to be charged. If this attribute is true, you should collect a PIN from the user and send it as part of the /customers/{customer_account_id}/stored-payment-methods request. The PIN is numeric with no specified length requirement. |
tokens.[i].bin_ranges.[i].rechargeable |
bool | false |
Whether gift card is rechargeable |
Gift Cards
When registering a Gift Card, you have to ensure that the gift card number provided by the customer falls into the range of one of the BIN ranges (at least first 3 digits) returned.
Additionally, in case the pin_required attribute is true for the identified BIN range, you need to prompt the customer to provide a PIN and send it as part of the /customers/{customer_account_id}/stored-payment-methods request.
For gift cards, gift card numbers can be posted directly to the PAR Ordering APIs and do not have to be posted to the payment processor directly / entered on a payment processor web app, since gift cards do not fall under PCI regulations.
Interact with Payment Processor to store Payment Method
How the card details are collected depends on the payment processor configured for your brand. New integrations use PAR Pay; its hosted card form, and the earlier Aurus flow, are described in the PAR Pay guide.
Store Payment Method
After the interaction with the Payment Processor has successfully been completed, you can make a call to POST /customers/{customer_account_id}/stored-payment-methods to store the payment method:
Retrieve Stored Payment Methods
GET /customers/{customer_account_id}/stored-payment-methods returns what the customer has saved, in the shape shown in the responses below. Which of them the customer can use at a given store comes from the store's available_payment_methods in GET /venues/{venue_id}?view=withNestedEntities.
Credit Cards
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
Authorization HTTP header |
string | "Bearer {customer_account_token}" |
JWT Token of Customer Account |
payment_method_id |
string | "0d6b5a4e-3f23-11ed-936c-1a67b454859d" |
UUID of the Credit Card payment method (type 1) from available_payment_methods in the init-application response. Not the numeric type id |
payment_processors |
array[PaymentProcessor] | One entry: the processor whose generate-tokens entry you followed |
|
payment_processors.[i].id |
string | "c2f3a1d4-7b8e-4c5f-9a0b-1d2e3f4a5b6c" |
UUID of Payment Processor - from /payment-processors/generate-tokens API call |
payment_processors.[i].properties.one_time_token |
string | "30910032626134340597000708770932" |
One-time token from the hosted card form. On PAR Pay (38) it is data.paymentMethodData.one_time_token from the form's transaction:success message, and it is the only property you send |
payment_processors.[i].properties.token |
string | "bc31e770-bbca-47bf-884b-27e2563a9033" |
Aurus (32) only. The token from the matching /payment-processors/generate-tokens entry, sent alongside one_time_token |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/customers/{customer_account_uuid}/stored-payment-methods",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json",
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvY3VzdG9tZXJzL3JlZnJlc2giLCJpYXQiOjE2OTEzMzA4NjUsImV4cCI6MTY5MTM3MjA1OCwibmJmIjoxNjkxMzY4NDU4LCJqdGkiOiJJT2IwQ0VteFNiZ21vTXlSIiwic2V0UmVmcmVzaFRUTCI6MjYyODAwMCwic3ViIjoiNTA5MDYzNyIsInBydiI6ImNjMzI5MjFhMTU0ODBhMTE3ZDliYmM3MmMwZTEyNTZhNjg1MjQ1OGIiLCJhcHBsaWNhdGlvbl9pZCI6MjAxNSwic2Vzc2lvbl9pZCI6MjY2MjF9.Y5zJQgx4j4fHrNebQoAn3bGtr_iHa6DSKfNjQfkvjvg"
},
"body": {
"payment_method_id": "0d6b5a4e-3f23-11ed-936c-1a67b454859d",
"payment_processors": [
{
"id": "c2f3a1d4-7b8e-4c5f-9a0b-1d2e3f4a5b6c",
"properties": {
"one_time_token": "30910032626134340597000708770932"
}
}
]
}
}
On PAR Pay the card is validated with a zero-amount authorization before it is saved; the customer may briefly see a $0 hold, but nothing is charged. On Aurus add "token": "bc31e770-bbca-47bf-884b-27e2563a9033" to properties, taken from the 32 entry of generate-tokens.
Response
{
"code": 200,
"data": {
"stored_payment_methods": [
{
"id": "85688223-b4ee-4c0f-8593-513c182ef7b1",
"properties": {
"card_type": "visa",
"masked_number": "901010******0004",
"expiration_date": "12/2024",
"last_four_digits": "0004"
},
"preselected": true,
"payment_method_id": "027b59de-97cb-48a0-9404-37f426659bad"
}
]
},
"status": "OK"
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
stored_payment_methods |
array[StoredPaymentMethods] | Array of Stored Payment Methods that belong to the customer account | |
stored_payment_methods.[i].id |
string | "85688223-b4ee-4c0f-8593-513c182ef7b1" |
ID of the stored payment method - will be used to initialize payment |
stored_payment_methods.[i].properties.card_type |
string | "visa" |
String ID for Card Type |
stored_payment_methods.[i].properties.masked_number |
string | "901010******0004" |
First 6 digits and last 4 digits of credit card number (PAN) - some payment processors may only return last 4 digits |
stored_payment_methods.[i].properties.expiration_date |
string | "12/2024" |
Month / Year in which credit card will expire |
stored_payment_methods.[i].properties.last_four_digits |
string | "0004" |
Last 4 digits of credit card number (PAN) |
stored_payment_methods.[i].preselected |
bool | true |
Defines which payment method should be pre-selected for the customer on checkout - based on last-touched (last-used) payment method for the customer |
stored_payment_methods.[i].payment_method_id |
string | "027b59de-97cb-48a0-9404-37f426659bad" |
UUID of a registered payment method |
Available card types:
- Visa
- MasterCard
- AmericanExpress
- Diners
- Maestro
- JCB
- Discover
- GiftCards
Gift Cards
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
Authorization HTTP header |
string | "Bearer {customer_account_token}" |
JWT Token of Customer Account |
payment_method_id |
string | "9b7d1577-0d3f-4839-a01c-6230419bfc35" |
UUID of the gift card payment method (type 14) from init-application. See Payment Processors and Payment Methods. |
payment_processors |
array[PaymentProcessor] | One entry, with the id of the processor whose generate-tokens entry carried the bin_ranges — the PAR Pay processor (38) itself, or the 35 gift card processor on an Aurus brand |
|
payment_processors.properties.gift_card_number |
string | "7321950000010535899" |
Gift card number provided by the customer (needs to fall into returned BIN ranges returned in /payment-processors/generate-tokens API response) |
payment_processors.properties.gift_card_code |
string | "123" |
Gift card PIN code, in case pin_required was true for the identified BIN range returned in the /payment-processors/generate-tokens API response |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/customers/{customer_account_uuid}/stored-payment-methods",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Content-Type": "application/json",
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvY3VzdG9tZXJzL3JlZnJlc2giLCJpYXQiOjE2OTEzMzA4NjUsImV4cCI6MTY5MTM3MjA1OCwibmJmIjoxNjkxMzY4NDU4LCJqdGkiOiJJT2IwQ0VteFNiZ21vTXlSIiwic2V0UmVmcmVzaFRUTCI6MjYyODAwMCwic3ViIjoiNTA5MDYzNyIsInBydiI6ImNjMzI5MjFhMTU0ODBhMTE3ZDliYmM3MmMwZTEyNTZhNjg1MjQ1OGIiLCJhcHBsaWNhdGlvbl9pZCI6MjAxNSwic2Vzc2lvbl9pZCI6MjY2MjF9.Y5zJQgx4j4fHrNebQoAn3bGtr_iHa6DSKfNjQfkvjvg"
},
"body": {
"payment_method_id": "9b7d1577-0d3f-4839-a01c-6230419bfc35",
"payment_processors": [
{
"id": "c2f3a1d4-7b8e-4c5f-9a0b-1d2e3f4a5b6c",
"properties": {
"gift_card_number": "7321950000010535899",
"gift_card_code": "123"
}
}
]
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"stored_payment_methods": [
{
"id": "5bab16ce-bb27-4e62-aff4-124266647eaf",
"payment_method_id": "9b7d1577-0d3f-4839-a01c-6230419bfc35",
"preselected": true,
"properties": {
"card_type": "GiftCard",
"masked_number": "XXXXXXXXXXXXXXXX8999",
"expiration_date": null,
"last_four_digits": "8999"
}
}
]
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
stored_payment_methods |
array[StoredPaymentMethods] | Array of Stored Payment Methods that belong to the customer account | |
stored_payment_methods.[i].id |
string | "85688223-b4ee-4c0f-8593-513c182ef7b1" |
ID of the stored payment method - will be used to initialize payment |
stored_payment_methods.[i].properties.card_type |
string | "GiftCard" |
String ID for Card Type |
stored_payment_methods.[i].properties.masked_number |
string | "901010******0004" |
First 6 digits and last 4 digits of gift card number - some payment processors may only return last 4 digits |
stored_payment_methods.[i].properties.last_four_digits |
string | "0004" |
Last 4 digits of gift card number |
stored_payment_methods.[i].preselected |
bool | true |
Defines which payment method should be pre-selected for the customer on checkout - based on last-touched (last-used) payment method for the customer |



