Charitable Braintree

Braintree is a payment service created by PayPal that allows you to accept donations securely on your website, while giving your donors the flexibility of paying via PayPal, Venmo (in the US), credit or debit cards, or digital wallets such as Google Pay and Apple Pay.

Installation

Installing Charitable Braintree is the same as installing any other Charitable extension. If you’re not sure how to do that, we recommend first reading our guide to installing Charitable extensions.

Setup

After the extension is installed, you will need to add your Braintree API keys. If you don’t have a Braintree account yet, now is the time to set one up:

https://www.braintreepayments.com/

Find your account settings

In order to begin using Braintree, you need to set your Merchant ID, Public Key and Private Key settings.

Go to Charitable > Settings > Payment Gateways > Braintree Gateway Settings.

For your live Braintree account (the one you log into at www.braintreegateway.com/login), these settings will be entered in the Live Mode Settings section.


When you first log into your Braintree account, or if you have never made any transactions through it, you will see your Merchant ID, Public Key and Private Key displayed immediately once you sign in:

Copy and paste these keys into your Charitable settings.

If you do not see this when you log into your Braintree account, you can follow the instructions below to find the relevant details:

  1. In the top right corner of your Braintree dashboard, click on the gear icon and then click on API.
  2. You’ll find your public key under the API Keys section at the top. If no API keys appear, click Generate New API Key.
  3. Click on the View link in the Private Key column. On the following screen, you will see your Private Key, Merchant ID and Public Key listed.
Copy and paste your Public Key, Private Key and Merchant ID to your Charitable Braintree settings.

Testing with a Sandbox account

To test out how Braintree works, we recommend testing it first with a sandbox account. You can create a sandbox account at https://sandbox.braintreegateway.com

You will find your Public Key, Private Key and Merchant ID in the same way as for a live account (see instructions above). Copy and paste these into the Test Mode Settings section in your Charitable Braintree settings.

Recurring Donations Setup

If you are using Braintree alongside our Recurring Donations extension, there are some additional setup steps.

Adding a Webhook

When a donor has a recurring donation, Braintree can send notifications to your website via a webhook whenever important subscription-related events happen, such as:

  • A renewal has been charged
  • The recurring donation has been cancelled
  • Braintree failed to process the most recent renewal

Without a webhook, Charitable would not be alerted to these events, so it is important to add a webhook.

  1. In the top right corner of your Braintree dashboard, click on the gear icon and then click on API.
  2. Click on the Webhooks link at the top.
  3. Click + Create a New Webhook to add your webhook.
  4. For Destination URL, enter your website URL appended by /charitable-listener/braintree/. For example, if your website is example.com, your Destination URL will be https://example.com/charitable-listener/braintree/.
  5. Under Notifications, check all options under Subscription.
Add a webhook and set it up to receive notifications for all subscription-related events.

Once you have added the webhook, click on Check URL to make sure the webhook is set up properly and can reach your website. Your server should respond with a 200 status.

If you are using the Braintree Sandbox to test things out, we also recommend adding a webhook in your sandbox account, following the same process.

Create a Recurring Billing Plan

In order to create a recurring donation through Braintree, you need to have a billing plan. When someone starts a recurring donation, a subscription will be created for them, using this plan.

Note: Even though the plan you create in Braintree will have a set price and billing frequency, these are default values. For individual subscriptions, a donor subscription can override these values. For this reason, it’s possible to use a single recurring billing plan for all recurring donations created through your website.

To create a billing plan in your Braintree dashboard:

  1. In the top navigation, click on Subscriptions.
  2. At the top of the page, click on Plans.
  3. If you are creating a new plan, click on + Create A Plan; if you are adding a new plan, click on + New Plan.
  4. For the plan settings, enter your plan’s name, default price, and default billing frequency. You may also prefer to specify a plan ID and description, though both are optional. All other settings should be left empty or unchanged.
  5. Click on Create.

Once you have created your plan, return to your website’s dashboard and navigate to the Braintree settings page (Charitable > Settings > Payment Gateways > Braintree Gateway Settings). Scroll down to the Recurring Billing section:

Select the default billing plans you would like to use for all recurring donations, both for Live Mode and Test Mode. For test mode, you will need to create a billing plan in your Braintree sandbox dashboard.

Using Different Plans for Different Campaigns

You may find it useful to define different recurring billing plans for different campaigns. For example, this can make it easier for you to find all recurring donations to a specific campaign in your Braintree dashboard.

To do this, you will first need to create as many plans as you require in your Braintree dashboard by following the steps described above. You can leave the default plan settings in Charitable unchanged.

To change the recurring billing plan used for a specific campaign, edit the campaign in your WordPress dashboard. Under the Recurring Donations section, select your preferred billing plan to use for the campaign. Note that there are separate settings for Live and Test Mode.

Override the billing plan to use for a particular campaign.