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.
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.
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:
gateway = Braintree::Gateway.new(
:access_token => access_token_for_recipient
grant_result = gateway.payment_method.grant(
: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".
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.
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.
Next Page: Configuration →