Braintree Module

Collect card payments through Braintree and offer saved cards or subscriptions for future renewals.

Reaching the Screen

Go to Settings → Financial → Payment Gateways, open All Modules and click the Braintree card: {admin}/modules/payment?module=Braintree

Adding the gateway to the method list clients see is covered in Payment Modules.

What Is on the Screen

One settings form: the Braintree key pair, an optional merchant account, two switches and the shared gateway settings every module carries.

Clients meet Braintree's own card panel inside the payment page, so they never leave your site. The card number goes straight to Braintree and your install keeps only a token.

The module keeps cards for later, charges a kept card on renewal, opens subscriptions and refunds a payment from the invoice screen. It does not accept a card number typed into your own form, and it offers no installments.

Before You Configure It

• A Braintree account with its public and private key. Sandbox keys and live keys are two separate pairs from two separate control panels.
• The currency you charge in enabled on a Braintree merchant account.
• For kept cards and automatic renewal payments, this module chosen under Card Storage Module in Initial Settings.
• For subscriptions, a Braintree plan per billing interval and a webhook. Creating the webhook requires Manage Webhooks permission at Braintree.

Fields

For status, commission, currency, amount and country limits, see Payment Modules. Update Subscription Fee updates Braintree's recurring amount when the renewal total changes; it defaults to off. Callback URL, Success URL and Failed URL cannot be edited; use their copy icons.

Tasks

Take the keys from Braintree

1. Sign in to the Braintree Control Panel. Sandbox and live are separate sites, so sign in to the one whose keys you want.
2. Click the gear icon at the top right, open API and find the API Keys section.
3. Open View in the Private Key column and copy that row's public and private keys. If none exist, use Generate New API Key.
4. One more step only if the default account does not settle your currency. Open the gear icon again, go to Business and copy the id from Merchant Accounts.

Enter the credentials

1. Open the module card and tick Status. The other fields stay locked until you do, and nothing else is saved while it is off.
2. Fill in Public Key and Private Key, and set Sandbox Mode to match the pair you entered.
3. Click Save Changes. Clients who pick this method now see the Braintree card panel.
4. Pay a test invoice using sandbox credentials and a Braintree test card. Check both the provider transaction and the invoice's Paid status.

Let clients keep their card

1. Go back to Settings → Financial → Payment Gateways and open Initial Settings.
2. Choose Braintree under Card Storage Module and click Save Changes.
3. Clients can now add a card from their account, pick a kept card while paying and turn on automatic payment.

Offer subscriptions

1. At Braintree, open Subscriptions → Plans → Create A Plan (or New Plan). Set the currency and monthly interval, then click Create. Repeat for each interval. Daily and weekly cycles are unavailable; prices are set per subscription.
2. Under the gear icon, open API → Webhooks → Create New Webhook. Paste Callback URL and select subscription_charged_successfully, subscription_went_active, subscription_went_past_due, subscription_canceled and subscription_expired. Click Create Webhook.
3. Back on the module card, tick Recurring Billing and click Save Changes.
4. The payment panel now offers automatic renewal for the lines whose cycle matches one of your plans. Lines with no matching plan are never offered.

What the client goes through

Card storage, automatic payment and subscription options require the account owner paying for their own account. Shared payment links do not offer them.

1. The client picks this method at checkout, on an invoice or when adding funds.
2. The card panel opens in place. The client enters a card or picks one kept earlier. Two tick boxes offer to keep the card and to pay future invoices with it.
3. When subscriptions are on, the client also picks which renewing lines join one agreement. Lines on different billing cycles cannot share an agreement.
4. Braintree charges the card. The payment closes the invoice and the service is activated.

Refund a payment

1. Open the paid invoice: {admin}/invoices/detail?id={invoice}
2. Under Summary → Change Status, select Refunded and Refund via payment gateway. Click Update Status.
3. Braintree returns the charge. A charge it has not settled yet is voided instead, with the same result for the client.

Things to Watch

Required Privileges

Payment Module Settings (MODULES_PAYMENT_SETTINGS) is required. Invoice refunds also require INVOICES_OPERATION.

Related Articles

• Payment Modules
• Invoice Detail Overview
• Subscriptions
• Module Management