availability

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:

User

Name Description
country Country
email 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

Name 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

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.add_on.<method>
Braintree::Address.<method> gateway.address.<method>
Braintree::ClientToken.<method> gateway.client_token.<method>
Braintree::CreditCard.<method> gateway.credit_card.<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.payment_method.<method>
Braintree::PaymentMethodNonce.<method> gateway.payment_method_nonce.<method>
Braintree::PaypalAccount.<method> gateway.paypal_account.<method>
Braintree::MerchantAccount.<method> gateway.merchant_account.<method>
Braintree::SettlementBatchSummary.<method> gateway.settlement_batch_summary.<method>
Braintree::Subscription.<method> gateway.subscription.<method>
Braintree::TransparentRedirect.<method> gateway.transparent_redirect.<method>
Braintree::Transaction.<method> gateway.transaction.<method>
Braintree::Testing.<method> gateway.testing.<method>
Braintree::Verification.<method> gateway.verification.<method>
Braintree::WebhookNotification.<method> gateway.webhook_notification.<method>
Braintree::WebhookTesting.<method> gateway.webhook_testing.<method>

OAuth scopes

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

Parameter Description
read_write Provides full read-write control of the merchant's Braintree account.
read_only Provides read-only access to the merchant's Braintree account.
shared_vault_transactions Allows Shared Vault transactions.

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

Payment method sharing

You can use the following parameters when creating a shared vault transaction with payment method sharing:

Name Description
shared_payment_method_token The payment method token of a card stored in the Partner's Vault that will be charged. Required for payment method sharing.
shared_customer_id The ID of a customer stored in the Partner's Vault. Will populate the customer_details of the transaction.
shared_billing_address_id The ID of an address in the Partner's Vault. Will populate the billing_address_details of the transaction.
shared_shipping_address_id The ID of an address in the Partner's Vault. Will populate the shipping_address_details of the transaction.

Parameters

Name Description
payment_method_token The payment method token of a card stored in the Partner's Vault. This is the card that will be made accessible to merchants receiving the granted nonce.
allow_vaulting Determines whether or not the granted nonce can be vaulted by the merchant.

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:

  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 on 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.

Still Have Questions?

If you can’t find an answer, give us a call at 877.434.2894 or contact our Support team