Server-side Connect Flow

Availability Braintree Auth is in closed beta. Contact us to express interest.

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.

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

BraintreeGateway gateway = new BraintreeGateway(
    "use_your_client_id",
    "use_your_client_secret"
);
string url = gateway.OAuth.ConnectUrl(new OAuthConnectUrlRequest {
    RedirectUri = "https://your.redirect.uri",
    Scope = "read_write",
    State = "foo_state",
    LandingPage = "signup",
    LoginOnly = false,
    User = new OAuthConnectUrlUserRequest {
        Country = "USA",
        Email = "[email protected]"
    },
    Business = new OAuthConnectUrlBusinessRequest {
        Name = "14 Ladders",
        RegisteredAs = "14.0 Ladders"
    },
    PaymentMethods = new string[] { "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. 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.