Braintree Auth (Beta)
Server-side Connect Flow
Regardless of whether you support new signups or allow only logins, the first step in the Connect integration is to set up the connect_url
. This URL is where the merchant will be sent after clicking the Connect with Braintree button, starting the OAuth flow. It is built by the Braintree server SDK.
- PHP
$gateway = new BraintreeGateway([
'clientId' => 'use_your_client_id',
'clientSecret' => 'use_your_client_secret'
]);
$url = $gateway->oauth()->connectUrl([
'redirectUri' => 'https://your.redirect.uri',
'scope' => 'read_write',
'state' => 'foo_state',
'landingPage' => 'signup',
'loginOnly' => 'false',
'user' => [
'country' => 'USA',
'email' => 'foo@example.com'
],
'business' => [
'name' => '14 Ladders',
'registeredAs' => '14.0 Ladders'
],
'paymentMethods' => [
'credit_card',
'paypal'
]
]);
Redirect URI
The redirect URI is where the merchant is returned when the OAuth flow is complete or if they chose to finish later. All redirect URIs must be allowlisted as part of your OAuth configuration.
Scope
The read_write
scope shown in the example allows for full control over the connected merchant's account and is the most commonly required scope for the ecommerce platform use case. This scope translates to the following permission requests in the Authorize step:
- Create and manage transactions on your behalf
- Create and manage customers on your behalf
- Update your account details
If you only need to access data in the merchant's Braintree account, such as transactions or customers, then you can instead request just a read_only
scope.
If you would like to request multiple scopes, use a comma separated string, e.g. read_write,shared_vault_transactions
.
State
The state
parameter is part of the OAuth 2.0 specification and used to prevent Cross Site Request Forgery (CSRF) attacks. Braintree will always return the submitted state
verbatim along with the access code when redirecting back to the redirect URI. You can verify the authenticity of the request to the redirect URI by submitting a non-guessable state
parameter when initiating the Connect flow and ensuring the value returned matches the value submitted.
You should ensure that the contents of the state
parameter are properly escaped (typically via base 64 or URL encoding) to prevent them from being altered by a merchant's browser when redirecting at the end of the OAuth flow.
Landing page
The first page all merchants see when clicking Connect with Braintree is the cobranded login page. For merchants who choose not to use Login with PayPal, the optional landing_page
parameter determines whether they are initially presented with the Braintree login or signup form.
If you support both logins and signups in your flow, the merchant can manually switch between both pages. If you expect most of your merchants will need one page or the other, however, it can be helpful to default to that page.
The two valid values that can be passed to this parameter are login
and signup
. If this parameter is not provided, the landing_page
will default to login
.
Supporting login-only
Set login_only
to true
in the Connect URL to ensure only existing Braintree merchants can connect to your platform.
If this parameter is not specified, merchants can either sign up for a new account or log into an existing account by default.
Supporting signups
Country and currency
If the merchant needs to sign up for a new account, the country code passed here will set the merchant's domiciled country, which in turn sets the currency for all their transactions. The currency set is always the domestic currency for that country. For example, accounts created using the USA
country code will only accept USD
transactions, for both presentment and settlement. Multiple presentment currencies per merchant can be added via the API.
Payment methods
By default the signup flow for new merchants will activate both credit card and PayPal payments. If the merchant does not have a PayPal account, a new PayPal account can be provisioned during the signup flow without requesting additional information beyond an email and password for login purposes.
You can specify credit_card
only in payment_methods
if you wish, but specifying paypal
only is not valid. Contact PayPal directly if you are looking for a PayPal-only merchant onboarding flow.
Pre-populating the form
You can pre-populate almost every signup field with any information you may have by passing it to connect_url
. See the available fields in the reference.
Next Page: Client-side Connect Flow →