Adding payments

As a partner, you can manage the payment information for the diners who order through your implementation. We use the Grant API through Braintree Payments. It securely allows one merchant to enable customer payments in another merchant's system.

To use this API, you'll need access to the following Braintree features:

1. Customer vaulting.
2. Braintree Auth.
3. The Grant API.

While you should consult the Braintree documentation on these functions, here's the basic steps that you need to implement to enable payments with Grubhub:

1. Authorize payments to Grubhub through Braintree Auth. You only have to do this once.
2. Attach a payment to a new or existing customer.
3. Generate a nonce using the Grant API.
4. Pass that nonce to /payments/partner_payment.
5. Attach the resulting payment_id to the diner's cart.

The first three steps use the Braintree API; their documentation will help you get running. For the last two steps, see the sections below.

Link Nonce to Payment ID

After the Braintree steps, you should have a nonce that we can use to pay for a diner's order. The first step is to generate a payment ID.

To generate a payment ID, POST the nonce to /payments/partner_payment. For example:

POST /payments/partner_payment HTTP/1.1
Host: api-gtm.grubhub.com
Authorization: Bearer 84e1024c-8a97-469e-b49c-195ebb60bfc6
Content-Type: application/json

{
    "payment_nonce" : "XXXXXXXXXXXXXXX",
  "vaulted": "false",
  "type": "CREDIT_CARD"
}

On success, this will return the id of the payment and the full uri that you can use to GET a secured version of the payment information. This object will look something like this:

{
    "id": "J1xnxaPdTKyysKo9mxziqQ",
    "uri": "/payments/mBVZAH0kEee5ZUE5jKZbTA/credit_card/J1xnxaPdTKyysKo9mxziqQ",
    "already_exists": false
}

To split a bill over multiple payment methods, you'll need to grant Grubhub access to each one, creating a payment from a Braintree nonce for each.

Add Payment to Cart

With our payment ID configured, we're ready to add it to the cart. For each payment method your diner wants to use on an order, they'll need to attach that payment individually and specify how much of the bill each covers.

To add payment to a cart, POST the payment_ID, payment type, and the amount of the bill to apply to this method to the /carts/{cart_id}/payments. For example:

POST /carts/CwNJoY8rEee3QaeudTGoRQ/payments HTTP/1.1
Host: api-gtm.grubhub.com
Authorization: Bearer aba6bde9-f9dc-447f-8d3c-fcb8a9351a21
Content-Type: application/json
Cache-Control: no-cache

{
    "payment_id": "J1xnxaPdTKyysKo9mxziqQ",
    "type": "CREDIT_CARD"
}

Notice in this example that we left out the amount. If you do that, the payment will apply to the total balance on the cart. If, at some point after applying this payment, you add additional charges, this payment method will cover them as well.

On success, this will respond with a JSON object that looks like this:

{
    "id": "19JXwI8zEeeeKKnfdwhIXg",
    "uri": "/carts/CwNJoY8rEee3QaeudTGoRQ/payments/19JXwI8zEeeeKKnfdwhIXg",
    "already_exists": false
}

You can make additional PUT, GET, and DELETE requests against the returned uri to update, view, or remove the payment details, respectively.

At this point, you are ready for checkout.