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

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:


Parameter Description
$country Country
$email Email address
$firstName First name
$lastName Last name
$phone Phone number
$dobYear Birth year (YYYY)
$dobMonth Birth month (MM)
$dobDay Birth day of month (DD)
$streetAddress Street address
$locality City
$region State or province
$postalCode Postal code


Parameter Description
$name Name of company
$registeredAs Registered name
$industry Industry code
$description Company description
$streetAddress Street address
$locality City
$region State or province
$postalCode Postal code
$country Country
$establishedOn Year and month business was established (yyyy-mm)
$annualVolumeAmount Annual transaction volume amount
$averageTransactionAmount Average transaction amount
$maximumTransactionAmount Maximum transaction amount
$shipPhysicalGoods Does your company ship physical goods (true/false)
$fulfillmentCompletedIn 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 $connectUrl to allow only logins.

Parameter Description
$loginOnly Only show the login form on the landing page (true/false).

Merchant API

The following table maps Braintree class methods to the Merchant API methods you’ll use when taking actions on behalf of a connected merchant.

Class method Partner API method
Braintree_Transaction::<method> $gateway->transaction()-><method>
Braintree_AddOn::<method> $gateway->addOn()-><method>
Braintree_Address::<method> $gateway->address()-><method>
Braintree_ClientToken::<method> $gateway->clientToken()-><method>
Braintree_CreditCard::<method> $gateway->creditCard()-><method>
Braintree_Customer::<method> $gateway->customer()-><method>
Braintree_Discount::<method> $gateway->discount()-><method>
Braintree_Merchant::<method> $gateway->merchant()-><method>
Braintree_OAuth::<method> $gateway->oauth()-><method>
Braintree_Plan::<method> $gateway->plan()-><method>
Braintree_PaymentMethod::<method> $gateway->paymentMethod()-><method>
Braintree_PaymentMethodNonce::<method> $gateway->paymentMethodNonce()-><method>
Braintree_PaypalAccount::<method> $gateway->paypalAccount()-><method>
Braintree_MerchantAccount::<method> $gateway->merchantAccount()-><method>
Braintree_SettlementBatchSummary::<method> $gateway->settlementBatchSummary()-><method>
Braintree_Subscription::<method> $gateway->subscription()-><method>
Braintree_TransparentRedirect::<method> $gateway->transparentRedirect()-><method>
Braintree_Transaction::<method> $gateway->transaction()-><method>
Braintree_Testing::<method> $gateway->testing()-><method>
Braintree_Verification::<method> $gateway->verification()-><method>
Braintree_WebhookNotification::<method> $gateway->webhookNotification()-><method>
Braintree_WebhookTesting::<method> $gateway->webhookTesting()-><method>

OAuth scopes

There are currently only four OAuth scopes available when building the $connectUrl. To request multiple scopes, use a comma separated string, e.g. read_write,shared_vault_transactions.

Parameter Description
grant_payment_method Allows usage of the Grant API on the merchant's behalf.
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.
shared_vault_transactions Allows Shared Vault transactions.

Merchant ID

The $merchantId 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:


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 $clientId and a $clientSecret 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 $connectUrl 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

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.

Still have questions?

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