Braintree Auth is in closed beta. To request access, email auth@braintreepayments.com.

Connect URL

The first step in the Connect integration is to set 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.


If your application is provided as downloadable software (like a CMS plugin), read our additional documentation on downloadable software before starting your integration.

gateway = Braintree::Gateway.new(
  :client_id => "use_your_client_id",
  :client_secret => "use_your_client_secret",

url = gateway.oauth.connect_url(
  :redirect_uri => "https://your.redirect.uri",
  :scope => "read_write",
  :state => "foo_state",
  :landing_page => "signup",
  :user => {
    :country => "USA",
    :email => "foo@example.com",
  :business => {
    :name => "14 Ladders",
    :registered_as => "14.0 Ladders",
  :payment_methods => ["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 whitelisted as part of your OAuth configuration.


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.


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 landing_page parameter determines whether the merchant lands on our login or signup page. From there, they can begin the OAuth flow by logging into an existing account or by creating a new one.

The two valid values that can be passed to this parameter are login and signup. If you expect your users to already have a Braintree account, you will likely want to use login. Otherwise, if you expect your users to be signing up with Braintree for the first time, use signup.

If this parameter is not provided and the specified scope is read_only, the landing_page will default to login. If a different scope is provided, then the landing_page will default to signup.

Country and currency


Currently Braintree Auth is only open to US merchants transacting in USD. Multi-currency is also not supported.

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.

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: Client-side Connect Flow →

Still have questions?

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