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.

Stored Payment Methods Screen Payment Method Selection Screen Payment Processor Web App in WebView
Stored-Payment-Methods.jpg
Payment-Method-Selection.jpg
Payment-Processor-Web-App-in-WebView.jpg

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