Additional Features/
Braintree Auth (Beta)/
Server-side Connect Flow

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.
  1. C#
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 = "transaction:sale,customer:create",
    State = "foo_state",
    LandingPage = "signup",
    LoginOnly = false,
    User = new OAuthConnectUrlUserRequest {
        Country = "USA",
        Email = "foo@example.com"
    },
    Business = new OAuthConnectUrlBusinessRequest {
        Name = "14 Ladders",
        RegisteredAs = "14.0 Ladders"
    },
    PaymentMethods = new string[] { "credit_card", "paypal" }
});

Redirect URIAnchorIcon

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.

ScopeAnchorIcon

The transaction:sale and customer:create scopes shown in the example allow your integration to create transactions and customers for the connected merchant. Request only the scopes required for the API operations your integration performs. For read-only access, request the corresponding resource scopes, such as transaction:find or customer:find.

To request multiple scopes, pass them as a comma-separated string. See the OAuth Reference for all supported scopes.

StateAnchorIcon

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 pageAnchorIcon

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-onlyAnchorIcon

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 signupsAnchorIcon

Country and currencyAnchorIcon

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 methodsAnchorIcon

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 formAnchorIcon

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: →