Overview

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 Grant API allows a Braintree merchant to provide another Braintree merchant controlled access to one of their customer's payment methods. Access to this payment method can be revoked at any time. Currently, credit cards, debit cards, and PayPal Channel Initiated Billing Agreements may be shared via the Grant API.

Who's involved

There are two parties involved in any grant:

Grantor: The Braintree merchant that owns the embedded experience and is sharing access to a payment method in their Vault. Typically, a grantor is an aggregator or a platform. The grantor is responsible for integrating with the Grant API.
Recipient: The Braintree merchant that is receiving a shared payment method from the grantor. In an embedded experience, the recipient is the merchant providing a product or service to the customer. Although the recipient is not the party that integrates with the Grant API, they are responsible for providing the grantor with consent to share payment methods with them via OAuth.

How it works

The recipient must first consent to receive payment information from the grantor. Typically, this only needs to be done once per relationship. Our configuration page describes how to set this up. Once the recipient has given their consent, the grantor can create payment method nonces on their behalf using Payment Method: Grant. For example:

Ruby

gateway = Braintree::Gateway.new(
  :access_token => access_token_for_recipient
)

grant_result = gateway.payment_method.grant(
  "the_payment_method_token",
  :allow_vaulting => true,
  :include_billing_postal_code => true
)
nonce_to_send_to_recipient = grant_result.payment_method_nonce.nonce
# ...

Payment Method: Grant returns a payment method nonce that the grantor is responsible for giving to the recipient. Unlike payment method nonce's which have a lifespan of 3 hours, the granted nonce if not used, expires 24 hours after being created. The recipient will use this nonce to create a transaction or store the payment method in their own Vault. Transactions that are created using payment methods shared by the grantor are referred to as "facilitated transactions".

Note

We recommend that the grantor verify cards before sharing them to ensure the payment information is valid.

If you wish to create transactions on another merchant's behalf using payment methods stored in your Vault, the Shared Vault feature allows that capability.

Restrictions

The Grant API does not allow transitive use of payment information: a grant recipient cannot perform a Payment Method: Grant API call or create a Shared Vault transaction using payment information that was granted to them via a third party. Facilitated transactions cannot be cloned via Transaction: Clone Transaction. If the receiving merchant chooses to leave Braintree in the future, we will not include any granted payment methods when we export their vaulted data to another payment gateway.