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

Follow these steps to test your integration with Braintree Auth.

OAuth sandbox testing

Signup flow

You will want to do all of your Merchant Connect tests using the sandbox. To get started:

  1. Configure the server SDK to use the sandbox OAuth client_id and a client_secret you were provided
  2. Set the client-side environment to sandbox

When you click the Connect with Braintree button in sandbox, we will present you with the signup form, just as we would in production. These fields can be pre-populated or completed manually.


No external credit checking or ID verification takes place while in the sandbox.

The signup fields will accept any dummy data with a few exceptions:

  • SSN: Should be a dummy value but can't be sequential or all the same number
  • Phone numbers: Must be a valid combination of area code + next 3 digits
  • Bank routing number: Must be valid; use one from this Chase list

Once you have connected with one merchant in the sandbox, you can use that account’s login information for future test flows without having to complete the form again.

Redirect and authorization grant

We support several test authorization codes that allow you to test the OAuth redirect without having to go through the entire OAuth flow. These codes can be used to trigger predetermined responses in your sandbox and to retrieve an access token using the create_token_from_code method.

The following auth codes are supported:

Auth Code Description
fake-valid-auth-code A valid auth code that can be exchanged for an access token and a refresh token
fake-used-auth-code An auth code that will be treated as a duplicate submission
fake-expired-auth-code An auth code that will be treated as expired

When using fake-valid-auth-code to obtain an access token, the returned token will be valid and can be used as any access token normally would. The only difference is that it will be able to take actions on behalf of your own merchant, rather than the merchant that authorized your application during the OAuth flow.

gateway = Braintree::Gateway.new(
  :client_id => "use_your_client_id",
  :client_secret => "use_your_client_secret",
result = gateway.oauth.create_token_from_code(
  :code => "fake-valid-auth-code",

access_token = result.credentials.access_token
expires_at = result.credentials.expires_at
refresh_token = result.credentials.refresh_token

By default, the returned token will have the read_write scope, but you can change that by appending the desired scope(s) to the auth code:

Auth Code (with scopes) Description
fake-valid-auth-code(read_only) Obtain an access token with read_only scope
fake-valid-auth-code(read_write,shared_vault_transactions) Obtain an access token with read_write and shared_vault_transactions scopes

Passing a different scope will simulate a user connecting using a connect_url built with that scope.

OAuth production testing

Once you are comfortable with the flow in the sandbox, you will want to do a test in production.

  1. Configure the server SDK to use the production OAuth client_id and a client_secret you were provided.
  2. Set the client-side environment to production.

After clicking Connect with Braintree, if you already have a production Braintree merchant account you can choose the “Already have an account?” tab to log in and authorize. If you choose to link the Braintree production account where you created your OAuth application, the Connect flow will work; however, you may not be able to run a test transaction as that account may not have been underwritten for accepting payments. To run a test transaction you will need to create a new account via Connect and complete the form with accurate personal and business information.

If you need or want to sign up to complete the full Connect flow, then be aware that you will need to provide accurate ID and business information, and a credit check will be run on the business owner.

Checkout integration

If you are enabling payments for your users, you must ensure your integration enables the full Braintree feature set. Below is a checklist of checkout integration items you'll need to implement.

Client SDK

Integrate with our Client SDKs to create a payment form for your merchants.

Advanced Fraud Management Tools

Braintree's Advanced Fraud Management Tools for credit card transactions are disabled by default for Braintree Auth.

If the connected merchant requires Advanced Fraud Management Tools, you must collect and pass device data on their behalf. Be sure to also pass options.skip_advanced_fraud_checking as false to collect device data.


If you're accepting PayPal using the Vault flow, you must collect and pass device data for those transactions. Implement the data collector on the checkout and any page where a transaction could be completed using a Vault token (e.g. on your cart page).

Transaction fields

When creating a transaction, ensure the following fields are always populated:

  1. Channel ID / BN Code: If you were assigned a PayPal BN code you can use this field and pass it for every transaction. This ensures every transaction is attributed to your platform.
  2. Order ID: This must be unique per transaction per merchant (the same IDs can be used for different merchants). This allows merchants to use our duplicate transaction checking and risk threshold rules. Also, if you display this value in your dashboard, merchants can more easily match up transactions in the Control Panel and PayPal console.
  3. Buyer/customer billing address (credit cards only): If the customer’s billing address is collected during checkout, it should always be passed in the transaction sale call. The minimum field requirements are street address, postal code, and country code (alpha-2 or 3). This allows the merchant to use the Address Verification System (AVS) in the Control Panel as well as card verification (if the Vault is being used).
  4. CVV (credit cards only): This should always be passed on single transaction requests if it is collected at checkout, as is recommended. This allows the merchant to set CVV rules in the Control Panel as well as use card verification (if the Vault is being used).

Next Page: Branding →