Skip to content

Braintree plugin documentation #662

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
reshmabidikar wants to merge 4 commits into
base: v3
Choose a base branch
from
Open

Braintree plugin documentation #662

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1b9230a
braintree plugin documentation
reshmabidikar Mar 12, 2026
0faa72f
fix scanning errors
reshmabidikar Mar 12, 2026
8520ee4
Add sections for plugin testing and integration
reshmabidikar Mar 23, 2026
2bea148
Minor improvements
reshmabidikar Mar 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions html5/_main_toc.html.slim
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,9 @@ nav.sidebar-nav
li
a.nav-link href="/latest/avatax-plugin.html"
| AvaTax Plugin
li
a.nav-link href="/latest/braintree-plugin.html"
| Braintree Plugin
li
a.nav-link href="/latest/notification_plugin.html"
| Notification Plugins
Expand Down
167 changes: 167 additions & 0 deletions userguide/tutorials/braintree-plugin.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
= Braintree Plugin

The https://github.com/killbill/killbill-braintree[Braintree Plugin] is a Kill Bill payment plugin for the https://www.braintreepayments.com/[Braintree payment gateway].

== Prerequisites

* Ensure that you have Kill Bill, Kaui, and the database set up as explained in the https://docs.killbill.io/latest/getting_started.html[__Getting Started Guide__].
* Ensure that you have https://curl.se/[_cURL_] installed. If you are on Windows, we recommend that you use https://git-scm.com/download/win[_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[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 https://docs.killbill.io/latest/plugin_installation#_plugin_installation[Plugin Installation Guide].

For example, to install the plugin via https://github.com/killbill/killbill-cloud/blob/master/kpm[KPM], you can run the following command:

[source,bash]
----
kpm install_java_plugin braintree-plugin --destination=<path_to_install_plugin>
----

You can also install the plugin via the https://aviate.killbill.io/home[Aviate UI] "Plugin Marketplace" tab. Refer to the <<aviate_integration, 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:

. Connect to the Kill Bill database.

. Run the https://github.com/killbill/killbill-braintree/blob/master/src/main/resources/ddl.sql[Braintree Plugin DDL].

== Plugin Configuration

The Braintree plugin requires the following properties:

[options="header",cols="1,1,1,1"]
|===
|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 https://docs.killbill.io/latest/userguide_configuration.html#global_configuration_properties[Kill Bill Configuration File] or on a per-tenant basis via the https://apidocs.killbill.io/tenant#add-a-per-tenant-configuration-for-a-plugin[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:

[source, bash]
----
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 https://aviate.killbill.io/home[Aviate UI] "Plugin Configuration" tab. Refer to the <<aviate_integration, Aviate Integration>> section below for more details.

// == Kaui Integration TBD

[[aviate_integration]]
== Aviate Integration

You can use the https://aviate.killbill.io/home[Aviate UI] to install/configure the plugin. Refer to the following demo:

++++
<div>
<script async src="https://js.storylane.io/js/v2/storylane.js"></script>
<div class="sl-embed" style="position:relative;padding-bottom:calc(49.85% + 25px);width:100%;height:0;transform:scale(1)">
<iframe loading="lazy" class="sl-demo" src="https://killbill.storylane.io/demo/8hxhjuek5f2o?embed=inline" name="sl-embed" allow="fullscreen" allowfullscreen style="position:absolute;top:0;left:0;width:100%!important;height:100%!important;border:1px solid rgba(63,95,172,0.35);box-shadow: 0px 0px 18px rgba(26, 19, 72, 0.15);border-radius:10px;box-sizing:border-box;"></iframe>
</div>
</div>
++++


[[testing_the_plugin]]
== 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:

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

. https://developer.paypal.com/braintree/articles/control-panel/vault/create[Create a customer] in Braintree with https://developer.paypal.com/braintree/docs/reference/general/testing#valid-card-numbers[test card details]. Save the **Customer ID** generated for future reference (it should be something like **620594365**).

. https://apidocs.killbill.io/account#create-an-account[Create] a Kill Bill account. Save the **accountId** for further use.

. https://apidocs.killbill.io/account#add-a-payment-method[Create] a payment method in Kill Bill using a https://developer.paypal.com/braintree/docs/reference/general/testing#payment-method-nonces[fake valid nonce] and the Braintree customer ID as follows:
+
[source, bash]
----
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`.

. Create an https://apidocs.killbill.io/invoice#create-external-charge-s[external charge] on the account.

. Use the `paymentMethodId` to https://apidocs.killbill.io/invoice#trigger-an-invoice-run[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:

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

. Invoke the `BraintreeTokenServlet` to obtain a token:
+
[source, bash]
----
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.

. Use the https://developer.paypal.com/braintree/docs/start/drop-in[Braintree Drop-in] implementation to gather the customer's payment details and obtain a payment nonce.

. Complete steps 2-4 from <<testing_the_plugin, 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.

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

A full end-to-end integration demo that demonstrates Braintree integration is available https://github.com/killbill/killbill-braintree-demo[here].
Loading