The Braintree Plugin is a Kill Bill payment plugin for the Braintree payment gateway.

Prerequisites

  • Ensure that you have Kill Bill, Kaui, and the database set up as explained in the Getting Started Guide.

  • Ensure that you have cURL installed. If you are on Windows, we recommend that you use Git Bash to run the cURL commands.

  • Ensure that you have a Braintree account. A Braintree sandbox account may be used for testing purposes. You can sign up for a free account at https://www.braintreepayments.com/sandbox.

Overview

The Braintree plugin allows you to process payments via the Braintree payment gateway. You can create a payment method, make a purchase, and view the transaction details in Kaui.

Plugin Installation

You can install the plugin as explained in the Plugin Installation Guide.

For example, to install the plugin via KPM, you can run the following command:

kpm install_java_plugin braintree-plugin --destination=<path_to_install_plugin>

You can also install the plugin via the Aviate UI "Plugin Marketplace" tab. Refer to the Aviate Integration section below for more details.

Database Configuration

The Braintree plugin requires some additional database tables. To create these tables, please follow the steps given below:

  1. Connect to the Kill Bill database.

  2. Run the Braintree Plugin DDL.

Plugin Configuration

The Braintree plugin requires the following properties:

Property Name Description Required Default Value

org.killbill.billing.plugin.braintree.btEnvironment

The Braintree environment to use.

Yes

-

org.killbill.billing.plugin.braintree.btMerchantId

Unique Braintree merchant identifier that tells the plugin which merchant account to process transactions under.

Yes

-

org.killbill.billing.plugin.braintree.btPublicKey

The public API key from your Braintree account used to authenticate API calls.

Yes

-

org.killbill.billing.plugin.braintree.btPrivateKey

The private API key from your Braintree account used alongside the public key to authenticate API calls.

Yes

-

These properties can be configured globally via the Kill Bill Configuration File or on a per-tenant basis via the Add a per-tenant configuration for a plugin endpoint. For example, to configure these properties for the bob/lazar tenant, you can use the following curl:

curl -v \
 -X POST \
 -u admin:password \
 -H 'X-Killbill-ApiKey: bob' \
 -H 'X-Killbill-ApiSecret: lazar' \
 -H 'X-Killbill-CreatedBy: admin' \
 -H 'Content-Type: text/plain' \
 -d 'org.killbill.billing.plugin.braintree.btEnvironment=sandbox
org.killbill.billing.plugin.braintree.btMerchantId=xxx
org.killbill.billing.plugin.braintree.btPublicKey=xxx
org.killbill.billing.plugin.braintree.btPrivateKey=xxx' \
 http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-braintree

Expected result: HTTP 201/204 and no validation errors in the response.

Alternatively, you can also configure these properties via the Aviate UI "Plugin Configuration" tab. Refer to the Aviate Integration section below for more details.

Aviate Integration

You can use the Aviate UI to install/configure the plugin. Refer to the following demo:

Testing the Plugin

Once the plugin is installed and configured, you can use it to process payments via the Braintree payment gateway. You can create a payment method, make a purchase, and view the transaction details in Kaui.

You can follow the steps given below to test the plugin:

  1. Ensure that the plugin is installed and configured as explained above.

  2. Create a customer in Braintree with test card details. Save the Customer ID generated for future reference (it should be something like 620594365).

  3. Create a Kill Bill account. Save the accountId for further use.

  4. Create a payment method in Kill Bill using a fake valid nonce and the Braintree customer ID as follows:

    curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     -X POST \
     --data-binary '{
       "pluginName": "killbill-braintree",
       "pluginInfo": {
         "properties": [
           {
             "key": "bt_nonce",
             "value": "fake-valid-nonce"
           },
           {
             "key": "bt_customer_id",
             "value": "xxx"
           }
         ]
       }
     }' \
     "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/paymentMethods?isDefault=true"

    Expected result: HTTP 201 and a response containing a paymentMethodId.

  5. Create an external charge on the account.

  6. Use the paymentMethodId to trigger payment (required only if the paymentMethodId is not set as the default payment method).

Integration

In order to use the Braintree plugin in your application, follow the steps given below:

  1. Ensure that the plugin is installed and configured as explained above.

  2. Invoke the BraintreeTokenServlet to obtain a token:

    curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    "http://localhost:8080/plugins/killbill-braintree/clientToken"

    Expected result: HTTP 200 and a client token payload.

  3. Use the Braintree Drop-in implementation to gather the customer’s payment details and obtain a payment nonce.

  4. Complete steps 2-4 from Testing the Plugin to create a Braintree customer, create a Kill Bill account, and add a Kill Bill payment method with the generated nonce and Braintree customer ID.

  5. Use the paymentMethodId to charge the customer as required.

A full end-to-end integration demo that demonstrates Braintree integration is available here.