Braintree Auth (Beta)

Referenceanchor

availability

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

Signup form fieldsanchor

For merchants who need to sign up for a new Braintree account, you can pre-populate the following fields in the signup form:

Useranchor

Parameter Description
countryCountry
emailEmail address
firstNameFirst name
lastNameLast name
phonePhone number
dobYearBirth year (YYYY)
dobMonthBirth month (MM)
dobDayBirth day of month (DD)
streetAddressStreet address
localityCity
regionState or province
postalCodePostal code

Businessanchor

Parameter Description
nameName of company
registeredAsRegistered name
industryIndustry code
descriptionCompany description
streetAddressStreet address
localityCity
regionState or province
postalCodePostal code
countryCountry
establishedOnYear and month business was established (yyyy-mm)
annualVolumeAmountAnnual transaction volume amount
averageTransactionAmountAverage transaction amount
maximumTransactionAmountMaximum transaction amount
shipPhysicalGoodsDoes your company ship physical goods (true/false)
fulfillmentCompletedInEstimated fulfillment completion (days as integer). Should be one of: 7, 14, 30, 60, 90
currencyCurrency
websiteWebsite

Login-only flowanchor

If you would prefer that only existing Braintree merchants connect to your platform, you can set up the connect_url to allow only logins.

Parameter Description
loginOnlyOnly show the login form on the landing page (true/false).

OAuth scopesanchor

There are currently three additional OAuth scopes available for Braintree Auth platforms when building the connectUrl. All of the standard OAuth scopes are also available. To request multiple scopes, use a comma separated string, e.g. read_write,oauth_app_receive_dispute_webhooks.

Parameter Description
manage_disputes Allows you to manage disputes for a connected merchant.
oauth_app_receive_dispute_webhooks Allows you to receive Dispute webhooks for a connected merchant.
read_only Provides read-only access to the merchant's Braintree account.
read_write Provides full read-write control of the merchant's Braintree account.

Merchant IDanchor

The merchant_id is returned in the OAuth redirect in the merchantId param after the merchant has completed the Connect Connect flow.

It is the unique identifier for the account in Braintree's systems so it can help with support issues. Also, if you wish to deep link to the Braintree Control Panel from your dashboard you will need this ID to construct the URL.

For example, to link to a transaction details page, the URL looks like this:

https://braintreegateway.com/merchants/merchant_id/transactions/transaction_id

Downloadable software flowanchor

If your product requires the merchant to download software (such as a downloadable shopping cart) you will need to do a little extra work to prevent shipping software with your client_id and a client_secret embedded, as they should always be kept secret.

One solution is to create an intermediary server that communicates with Braintree on behalf of the merchant:

  1. When creating your OAuth application, register a redirect URI that points to your intermediary server: https://intermediaryserver.com/braintree-redirect
  2. After the merchant downloads your software, the host URL (e.g. https://cartuser.com) makes a request to this intermediary server, including the URI where the merchant will be directed at the end of the authorization flow: https://cartuser.com/oauth/braintree
  3. Your intermediary server returns the URI generated by your server, passing an escaped version of the merchant's URI (typically as a URL or base 64 encoded string) in the state param: https://braintreegateway.com/oauth/connect?state=https%3A%2F%2Fcartuser.com%2Foauth%2Fbraintree
  4. When the merchant clicks Connect with Braintree, the downloaded software redirects the merchant to the Braintree connect_url returned by your intermediary server in #3
  5. On completing the OAuth flow the merchant is redirected to the intermediary server using the URI registered in #1: https://intermediaryeserver.com/braintree-redirect?refresh_token=test&state=https://cartuser.com/oauth/braintree
  6. Your intermediary server inspects the state param of the redirect and uses it to redirect your merchant back to the URI given in the initiating request: https://cartuser.com/oauth/braintree?access_token=test
important

In this example the state parameter is insecure. See the notes in the server-side implementation section to ensure that you are using it properly in your application.

Merchant account validation errorsanchor

The following validation errors are specific to creating merchant accounts via Braintree Auth. You may receive additional validation errors on other objects; for details on those, see the main validation errors reference.

Code Text Explanation
93618Currency passed is not accepted.

The currency passed is not one of the supported currencies .

93621Merchant account was not OAuth onboarded.

Merchant was not onboarded through

Braintree Auth

.

93622Company name is not valid

The applicant's company name must contain only letters, numbers, and these characters: &-!@#$()'./+,". The maximum length is 40 characters.

83601Email is required.

Email is required.

93602Email is invalid.

Email is invalid.

83603Merchant must have a country code (alpha2, alpha3, numeric or name)

Merchant must have a country code (alpha2, alpha3, numeric or name)

93604Country code (alpha3) is not an accepted country.

Country code (alpha3) is not an accepted country.

93605Country code (alpha3) is not a valid country

Country code (alpha3) is not a valid country

93606Country code (alpha2) is not an accepted country.

Country code (alpha2) is not an accepted country.

93607Country code (alpha2) is not a valid country

Country code (alpha2) is not a valid country

93608Country code (numeric) is not an accepted country.

Country code (numeric) is not an accepted country.

93609Country code (numeric) is not a valid country

Country code (numeric) is not a valid country

93610Country name is not an accepted country.

Country name is not an accepted country.

93611Country name is not a valid country

Country name is not a valid country

93612Provided country information is inconsistent.

Provided country information is inconsistent.

93613One or more payment methods passed are not accepted.

One or more payment methods passed are not accepted.

93614One or more currencies passed are not accepted.

One or more currencies passed are not accepted.

93615One or more payment methods passed are not allowed.

One or more payment methods passed are not allowed.

93616A merchant account already exists for that currency.

A merchant account already exists for that currency.

93617You must pass in a valid currency.

You must pass in a valid currency.

93619No merchant accounts exist for merchant.

No merchant accounts exist for merchant.

93620A merchant account already exists for the id.

A merchant account already exists for the id.

936996Required attribute is missing

The missing attribute is provided in the error message.

936997Attribute is not in the required format

The attribute and the expected format are provided in the error message.

936998Attribute is not in the list of expected values

The attribute and the expected values are provided in the error message.

936999Attribute is the wrong type

The attribute and the expected types are provided in the error message.