Webhooks

Availability

The Grant API is currently in a limited release.Contact us to determine whether it's right for your needs and to request access to the API.

The grantor can manage which notifications they receive by configuring webhooks with Braintree. They'll manage the endpoints in the Braintree Control Panel by clicking the gear icon in the top right corner, selecting API from the drop-down menu, and then clicking on the Webhooks tab.

Before you get started

If you are not using webhooks already, follow the general webhooks guide to configure webhooks in your gateway.

Transaction notifications

Availability

Transaction status webhooks for the Grant API are not enabled by default and are in limited release. Contact braintreeextend@braintreepayments.com for details.

Any transactions made with granted payment methods will trigger a webhook notification with details of that transaction. The transaction object in the webhook payload will include both facilitated_details and facilitator_details.

Payment method updates

Once the recipient has vaulted a granted payment method, there are two versions of this payment method in the Braintree system: the version in the grantor's Vault and the version in the recipient's Vault. To ensure granted payment methods act like normal payment methods, we give recipients the ability to update them. The grantor can also update their version. When a granted payment method (either the original version or granted version) is updated, all associated merchants are updated with a webhook notification. The goal of the webhook is to give the party with outdated payment info the ability to update any details that might affect a payment method's chances of being declined. Only updates to these decline-relevant fields will trigger the webhook. For credit cards these are:

Expiration month
Expiration year
Card number
Billing address zip code

The webhook will contain a payment method token, the merchant IDs associated with the payment method, a list of those decline-relevant fields that were updated, and a new payment method nonce. The nonce can be used as the input for a typical , which will refresh the version of the listed fields with the new values from the update that triggered the webhook.
See the Grant API webhooks reference for more details.

Example

A Visa card with the expiration date of 10/2017 is granted to a recipient. Time passes and the customer updates the Visa card with to set the expiration date to 10/2022. The recipient would receive a webhook notification with the new expiration date and they could update their version with the new date. Later on, the customer updates the expiration date with the recipient to 10/2022. The recipient would receive a notification with the new expiration date of 10/2022. One way to update this expiration date on the grantor's version of the payment method would be to set up logic that updates the version as long as the new date is further in the future.