The Grant API is currently in a limited release. To determine whether it's right for your needs and to request access to the API, contact commerce-infrastructure@braintreepayments.com.

Before you get started

You can manage which notifications you receive by configuring webhooks with Braintree. You'll manage your endpoints in the Braintree Control Panel under Settings > Webhooks.

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

Transaction notifications


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

Any transactions made with payment methods you have granted 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 a receiving merchant has vaulted a granted payment method, there are two versions of this payment method in the Braintree system: the version in your Vault and the version in the receiving merchant's Vault. To ensure granted payment methods act like normal payment methods, we give recipients the ability to update them. As the grantor, you can also update your 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 PaymentMethod.update(), which will refresh your 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.


You grant a Visa card with the expiration date of 10/2017 to a merchant. Time passes and your customer updates the Visa card with you to set the expiration date to 10/2019. 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/2020. You would receive a notification with the new expiration date of 10/2020. One way to update this expiration date on your version of the payment method would be to set up logic that updates your version as long as the new date is further in the future.

See also

Next: Revocation →

Still have questions?

If you can’t find an answer, contact our Support team.