Braintree Auth (Beta)
Reference
Signup form fields
For merchants who need to sign up for a new Braintree account, you can pre-populate the following fields in the signup form:
User
Parameter | Description |
---|---|
country | Country |
Email address | |
first_name | First name |
last_name | Last name |
phone | Phone number |
dob_year | Birth year (YYYY) |
dob_month | Birth month (MM) |
dob_day | Birth day of month (DD) |
street_address | Street address |
locality | City |
region | State or province |
postal_code | Postal code |
Business
Parameter | Description |
---|---|
name | Name of company |
registered_as | Registered name |
industry | Industry code |
description | Company description |
street_address | Street address |
locality | City |
region | State or province |
postal_code | Postal code |
country | Country |
established_on | Year and month business was established (yyyy-mm) |
annual_volume_amount | Annual transaction volume amount |
average_transaction_amount | Average transaction amount |
maximum_transaction_amount | Maximum transaction amount |
ship_physical_goods | Does your company ship physical goods (true/false) |
fulfillment_completed_in | Estimated fulfillment completion (days as integer). Should be one of: 7, 14, 30, 60, 90 |
currency | Currency |
website | Website |
Login-only flow
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 |
---|---|
login_only | Only show the login form on the landing page (true/false). |
OAuth scopes
There are currently three additional OAuth scopes available for Braintree Auth platforms when
building the connect_url. 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 ID
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 flow
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:
- When creating your OAuth application, register a redirect URI that points to your intermediary
server:
https://intermediaryserver.com/braintree-redirect
- 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
- 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
- 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 - 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
- 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
Merchant account validation errors
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 |
---|---|---|
93618 | Currency passed is not accepted. | The currency passed is not one of the supported currencies. |
93621 | Merchant account was not OAuth onboarded. | Merchant was not onboarded through Braintree Auth . |
93622 | Company name is not valid | The applicant's company name must contain only letters, numbers, and these characters:
|
83601 | Email is required. | Email is required. |
93602 | Email is invalid. | Email is invalid. |
83603 | Merchant must have a country code (alpha2, alpha3, numeric or name) | Merchant must have a country code (alpha2, alpha3, numeric or name) |
93604 | Country code (alpha3) is not an accepted country. | Country code (alpha3) is not an accepted country. |
93605 | Country code (alpha3) is not a valid country | Country code (alpha3) is not a valid country |
93606 | Country code (alpha2) is not an accepted country. | Country code (alpha2) is not an accepted country. |
93607 | Country code (alpha2) is not a valid country | Country code (alpha2) is not a valid country |
93608 | Country code (numeric) is not an accepted country. | Country code (numeric) is not an accepted country. |
93609 | Country code (numeric) is not a valid country | Country code (numeric) is not a valid country |
93610 | Country name is not an accepted country. | Country name is not an accepted country. |
93611 | Country name is not a valid country | Country name is not a valid country |
93612 | Provided country information is inconsistent. | Provided country information is inconsistent. |
93613 | One or more payment methods passed are not accepted. | One or more payment methods passed are not accepted. |
93614 | One or more currencies passed are not accepted. | One or more currencies passed are not accepted. |
93615 | One or more payment methods passed are not allowed. | One or more payment methods passed are not allowed. |
93616 | A merchant account already exists for that currency. | A merchant account already exists for that currency. |
93617 | You must pass in a valid currency. | You must pass in a valid currency. |
93619 | No merchant accounts exist for merchant. | No merchant accounts exist for merchant. |
93620 | A merchant account already exists for the id. | A merchant account already exists for the id. |
936996 | Required attribute is missing | The missing attribute is provided in the error message. |
936997 | Attribute is not in the required format | The attribute and the expected format are provided in the error message. |
936998 | Attribute is not in the list of expected values | The attribute and the expected values are provided in the error message. |
936999 | Attribute is the wrong type | The attribute and the expected types are provided in the error message. |