availability

Braintree Auth is in closed beta. To express interest, contact our Business Development team.

Braintree Auth follows the OAuth 2.0 spec.

Redirect and authorization grant

After completion of the Connect flow, the merchant is sent to the $redirectUri you provide to $connectUrl. An authorization code is returned by Braintree in the query string, along with the$state parameter you passed to $connectUrl.

Here is an example URL we would redirect to, given a $redirectUri of https://your.redirect.uri/callback, and a $state of foo_state:

https://your.redirect.uri/callback?state=foo_state&merchantId=g8cnjbnz83htzgm4&code=8b2cd3963a318b2e

Notice that you also receive back a merchantId. This is a unique identifier for the account in Braintree's systems, so it can be very useful for support issues; it's also used to construct deep links to the Braintree Control Panel. See more details on merchantId in the reference.

Getting an access token

You must exchange the authorization code in the query string for an $accessToken. The $accessToken is used to perform actions on a merchant's behalf. The following example creates an $accessToken:

PHP
Copy
Copied
$gateway = new Braintree_Gateway([
    'clientId' => 'use_your_client_id',
    'clientSecret' => 'use_your_client_secret'
]);

$result = $gateway->oauth()->createTokenFromCode([
    'code' => codeFromQueryString
]);

$accessToken = $result->credentials->accessToken;
$expiresAt = $result->credentials->expiresAt;
$refreshToken = $result->credentials->refreshToken;

Using an access token

You’ll use the access token to perform actions on the merchant’s behalf via the Merchant API.

Managing access tokens

The $accessToken will expire 10 years from its creation date. If you ever need to exchange the $accessToken (e.g. if the current token is expiring soon or you think it has been compromised in some way), you can use the $refreshToken to get a new one. The $refreshToken is provided when you get the initial access token.

PHP
Copy
Copied
$gateway = new Braintree_Gateway([
    'clientId' => 'use_your_client_id',
    'clientSecret' => 'use_your_client_secret'
]);

$result = $gateway->oauth()->createTokenFromRefreshToken([
    'refreshToken' => useTheRefreshToken
]);

$accessToken = $result->credentials->accessToken;
$expiresAt = $result->credentials->expiresAt;
$refreshToken = $result->credentials->refreshToken;

You can then revoke the use of the original access token by providing it to the revoke access token API.

PHP
Copy
Copied
$gateway = new Braintree_Gateway([
    'clientId' => 'use_your_client_id',
    'clientSecret' => 'use_your_client_secret'
]);

$result = $gateway->oauth()->revokeAccessToken(merchantAccessToken);

The connected merchant can revoke OAuth access via the Control Panel. You can be notified of this event by setting up the OAuth access revoked webhook.

Using a revoked access token on behalf of a merchant via the Merchant API will result in an authentication error.

Next Page: Webhooks →

Still have questions?

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