Using stored diner payments

Instead of using Braintree token to create a new payment, you can add a payment that a diner has attached to their account in a previous order. This simplifies the payment process.

NOTE: For integrations that use existing Grubhub.com diners instead of maintaining them in their records, this will be the primary way that you add a payment method to a cart. Integrations that follow a reorder-only flow will only need this payment flow.

There are three steps to adding an existing payment:

1. Get existing payment methods.
2. Get the payment method's ID.
3. Attach payment to cart.

Get existing payment methods

Repeat diners will probably have one or more payment methods attached to their account. So you will not have to send them through the add a payment type flow every time. Instead, you can get those payments already there.

To do so, call POST /kendo/get-available-entitlement-types to get the existing payment types. You can call this with an empty body to use the current cart of the currently logged in diner.

This will return something like this:

{
    "available_entitlement_types": [
        {
            "entitlement_type": "CREDIT_CARD",
            "detail_url": "/payments/mBVZAH0kEee5ZUE5jKZbTA/credit_card"
        },
        {
            "entitlement_type": "APPLE_PAY",
            "detail_url": null
        },
        {
            "entitlement_type": "PAYPAL_EXPRESS",
            "detail_url": "/payments/mBVZAH0kEee5ZUE5jKZbTA/paypal_express"
        },
        {
            "entitlement_type": "AMEX_EXPRESS",
            "detail_url": null
        },
        {
            "entitlement_type": "ANDROID_PAY",
            "detail_url": null
        },
        {
            "entitlement_type": "VENMO_PAY",
            "detail_url": null
        },
        {
            "entitlement_type": "PROMO_CODE",
            "detail_url": null
        },
        {
            "entitlement_type": "CASH",
            "detail_url": null
        }
    ]
}

Each entitlement_type that has a non-null detail_url represents an existing payment method that you can reuse in new carts.

Get the payment method ID

Call the detail_url to get the details on a given payment method. That call should look something like this:

GET /payments/mBVZAH0kEee5ZUE5jKZbTA/credit_card HTTP/1.1
Host: https://api-gtm.grubhub.com
Authorization: Bearer xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
Content-Type: application/json

This returns the following payload:

[
    {
        "id": "J1xnxaPdTKyysKo9mxziqQ",
        "diner_id": "mBVZAH0kEee5ZUE5jKZbTA",
        "credit_card_type": "Visa",
        "credit_card_last4": "1881",
        "payment_name": null,
        "expiration_date": 1580515200000,
        "expiration_month": 1,
        "expiration_year": 2020,
        "create_date": 1522786246013,
        "last_used_date": 1534270631705,
        "expired": false,
        "nonce": null
    }
]

If there are multiple items on a single payment type - such as multiple credit cards - they will all show up as objects in this array. The example above only has one credit card.

We recommend that you use this information in your user interface in order to help your diners select the payment method that they want to use.

For this process, however, you will want to make note of the id field. That value can be used to attach the payment method to the cart in the next section.

Attach the payment

The final step is to attach the payment to the cart. To do that, call POST /carts/{cart_id}/payments with a payment ID, type, and amount, as show below:

POST /carts/Zb-CsNfMEeimfxlO_bYzMw/payments HTTP/1.1
Host: https://api-pp.grubhub.com
Authorization: Bearer xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
Content-Type: application/json
{
  "payment_id": "J1xnxaPdTKyysKo9mxziqQ",
  "type": "CREDIT_CARD"
}

In the example above, the amount field has been omitted. In that case, the amount for this payment method will equal the entire remaining cart balance.

This returns a payload that looks like this:

{
    "id": "V4resN1JEeico-lmwvTshg",
    "uri": "/carts/Zb-CsNfMEeimfxlO_bYzMw/payments/V4resN1JEeico-lmwvTshg",
    "already_exists": false
}

The uri field here can be used to update or remove this payment as it applies to the given cart.