Using payment method details for loyalty programs

Use the Toast orders API to get guest payment method details so you can identify loyalty credit card transactions and award points.

Overview

Getting payment method details takes two steps. First, get the payment GUIDs for the orders you need to award points for. Then send a POST request to /orders/v2/payments/payment-method/search with the payment GUIDs in the request body. The response includes the bank identification number (BIN) and the last four digits of a guest's credit card (their payment method, which you can use to identify loyalty credit card transactions and apply loyalty points.

Important

You need the orders.payment-method:read scope to access this endpoint. For more information, see Scopes.

Getting payment method details to award loyalty points

The following procedure describes how to get payment method details and identify guest loyalty credit card transactions so you can award loyalty points.

To get payment method details to award loyalty points

1. Obtain payment GUIDs

   Get payment GUIDs using either of the following methods.

   • Orders API: Send a GET request to the /ordersBulk endpoint for multiple orders or to the /orders/guid endpoint for a single order. In each response, note the value of the guid field in the payments array for each payment you want to look up. For more information, see Getting detailed information about multiple orders and Getting detailed information about one order.

   • Orders webhook: Subscribe to the orders webhook to get order updates. Keep track of payment GUIDs for each order.

2. Use the orders API payment-method/search endpoint

   Send a POST request to the /orders/v2/payments/payment-method/search endpoint to retrieve detailed information about an order's payment method. The body of the request should be a JSON array of payment GUIDs, collected from step 1. You can look up multiple payments at a time.

   The response contains a PaymentDetails object per payment. Each object includes:

   Value	Description
   guid	The payment GUID.
   entityType	The object type. It is always PaymentMethod for this endpoint.
   externalId	The external identifier used to reference the entity from an external system. This value is null when no external ID is set.
   type	The payment method. In this response, the type is always CREDIT indicating the payment method was a credit card.
   first6Digits	The first six digits (BIN) of the credit card used.
   last4Digits	The last four digits of the credit card used.

   Note

   The response does not include guest names.

3. Award loyalty points

   Once you have identified the BIN and last four digits of a guest's payment method, you can identify the guest's loyalty account. Apply points to the guest's loyalty account using your loyalty system.

Example request and response

The following examples show the request and response using the payment-method/search endpoint.

Example request

[
  "c35cd503-c2ac-44ca-8023-49e140a7113d",
  "7929b90b-73f4-49be-860e-8b45936b0690"
]

You can include multiple payment GUIDs in your request body. The orders API returns a separate entry in the response for each payment GUID you include.

Example response

[
  {
    "guid": "c35cd503-c2ac-44ca-8023-49e140a7113d",
    "entityType": "PaymentMethod",
    "externalId": null,
    "type": "CREDIT",
    "first6Digits": "432551",
    "last4Digits": "8734"
  },
  {
    "guid": "7929b90b-73f4-49be-860e-8b45936b0690",
    "entityType": "PaymentMethod",
    "externalId": null,
    "type": "CREDIT",
    "first6Digits": "432214",
    "last4Digits": "7761"
  }
]