From 1b9230a86e2061ab6073186883d1af84c4ac3704 Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Thu, 12 Mar 2026 11:16:23 +0530 Subject: [PATCH 1/4] braintree plugin documentation --- html5/_main_toc.html.slim | 3 + userguide/tutorials/braintree-plugin.adoc | 87 +++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 userguide/tutorials/braintree-plugin.adoc diff --git a/html5/_main_toc.html.slim b/html5/_main_toc.html.slim index ada6fb59b..3193bb8c8 100644 --- a/html5/_main_toc.html.slim +++ b/html5/_main_toc.html.slim @@ -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 diff --git a/userguide/tutorials/braintree-plugin.adoc b/userguide/tutorials/braintree-plugin.adoc new file mode 100644 index 000000000..d95aee6b4 --- /dev/null +++ b/userguide/tutorials/braintree-plugin.adoc @@ -0,0 +1,87 @@ += 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.haxx.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 + +== 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= +---- + +You can also install the plugin via the https://aviate.killbill.io/home[Aviate UI] via the "Plugin Marketplace" tab. Refer to the <> 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.|No | DEFAULT + +|=== + +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 +---- + +Alternative, you can also configure these properties via the https://aviate.killbill.io/home[Aviate UI] by navigating to the "Plugin Configuration" tab. Refer to the <> section below for more details. + +// == Kaui Integration TBB + +== Aviate Integration + +You can use the https://aviate.killbill.io/home[Aviate UI] to install/configure the plugin. the following demo + +++++ +
+ +
+ +
+
+++++ + + + + + From 0faa72f611ae79173cb03dac57a698eb81d8f773 Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Thu, 12 Mar 2026 11:40:47 +0530 Subject: [PATCH 2/4] fix scanning errors --- userguide/tutorials/braintree-plugin.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/userguide/tutorials/braintree-plugin.adoc b/userguide/tutorials/braintree-plugin.adoc index d95aee6b4..f09e2fcd1 100644 --- a/userguide/tutorials/braintree-plugin.adoc +++ b/userguide/tutorials/braintree-plugin.adoc @@ -68,6 +68,7 @@ Alternative, you can also configure these properties via the https://aviate.kill // == Kaui Integration TBB +[[aviate_integration]] == Aviate Integration You can use the https://aviate.killbill.io/home[Aviate UI] to install/configure the plugin. the following demo From 8520ee4bf99bb0cf6d1174e125a0f9848767caf5 Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Mon, 23 Mar 2026 13:50:10 +0530 Subject: [PATCH 3/4] Add sections for plugin testing and integration --- userguide/tutorials/braintree-plugin.adoc | 112 +++++++++++++++++++++- 1 file changed, 109 insertions(+), 3 deletions(-) diff --git a/userguide/tutorials/braintree-plugin.adoc b/userguide/tutorials/braintree-plugin.adoc index f09e2fcd1..b07536e4a 100644 --- a/userguide/tutorials/braintree-plugin.adoc +++ b/userguide/tutorials/braintree-plugin.adoc @@ -10,6 +10,8 @@ The https://github.com/killbill/killbill-braintree[Braintree Plugin] is a Kill B == 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]. @@ -21,7 +23,7 @@ For example, to install the plugin via https://github.com/killbill/killbill-clou kpm install_java_plugin braintree-plugin --destination= ---- -You can also install the plugin via the https://aviate.killbill.io/home[Aviate UI] via the "Plugin Marketplace" tab. Refer to the <> section below for more details. +You can also install the plugin via the https://aviate.killbill.io/home[Aviate UI] "Plugin Marketplace" tab. Refer to the <> section below for more details. == Database Configuration @@ -64,14 +66,14 @@ org.killbill.billing.plugin.braintree.btPrivateKey=xxx' \ http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-braintree ---- -Alternative, you can also configure these properties via the https://aviate.killbill.io/home[Aviate UI] by navigating to the "Plugin Configuration" tab. Refer to the <> section below for more details. +Alternatively, you can also configure these properties via the https://aviate.killbill.io/home[Aviate UI] "Plugin Configuration" tab. Refer to the <> section below for more details. // == Kaui Integration TBB [[aviate_integration]] == Aviate Integration -You can use the https://aviate.killbill.io/home[Aviate UI] to install/configure the plugin. the following demo +You can use the https://aviate.killbill.io/home[Aviate UI] to install/configure the plugin. Refer to the following demo: ++++
@@ -83,6 +85,110 @@ You can use the https://aviate.killbill.io/home[Aviate UI] to install/configure ++++ +== 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. 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**). + +3. https://apidocs.killbill.io/account#create-an-account[Create] a Kill Bill account. Save the **accountId** for further use. + +4. 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//paymentMethods?isDefault=true" +---- + +5. Create an https://apidocs.killbill.io/invoice#create-external-charge-s[external charge] on the account. + +6. 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). + +## Integration + +In order to use the Braintree plugin, 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: + +[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" +---- + +3. 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. + +4. https://developer.paypal.com/braintree/docs/guides/customers[Create a customer] in Braintree. Save the **Customer ID** generated for future reference (it should be something like **620594365**). + +5. https://apidocs.killbill.io/account#create-an-account[Create] a Kill Bill account. Save the **accountId** for further use. + +6. https://apidocs.killbill.io/account#add-a-payment-method[Create] a payment method in Kill Bill using the 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": "xxx" + }, + { + "key": "bt_customer_id", + "value": "xxx" + } + ] + } + }' \ + "http://127.0.0.1:8080/1.0/kb/accounts//paymentMethods?isDefault=true" +---- + +7. 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]. From 2bea1485e329794796bbb71bb2c033758128bb43 Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Mon, 23 Mar 2026 15:14:44 +0530 Subject: [PATCH 4/4] Minor improvements --- userguide/tutorials/braintree-plugin.adoc | 83 ++++++++--------------- 1 file changed, 28 insertions(+), 55 deletions(-) diff --git a/userguide/tutorials/braintree-plugin.adoc b/userguide/tutorials/braintree-plugin.adoc index b07536e4a..42bcd642d 100644 --- a/userguide/tutorials/braintree-plugin.adoc +++ b/userguide/tutorials/braintree-plugin.adoc @@ -5,7 +5,7 @@ The https://github.com/killbill/killbill-braintree[Braintree Plugin] is a Kill B == 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.haxx.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 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 @@ -41,11 +41,10 @@ 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.|No | DEFAULT - +|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: @@ -66,9 +65,11 @@ 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 <> section below for more details. -// == Kaui Integration TBB +// == Kaui Integration TBD [[aviate_integration]] == Aviate Integration @@ -85,20 +86,21 @@ You can use the https://aviate.killbill.io/home[Aviate UI] to install/configure ++++ +[[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: -1. Ensure that the plugin is installed and configured as explained above. - -2. 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**). +. Ensure that the plugin is installed and configured as explained above. -3. https://apidocs.killbill.io/account#create-an-account[Create] a Kill Bill account. Save the **accountId** for further use. +. 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**). -4. 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: +. 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 \ @@ -125,19 +127,21 @@ curl -v \ }' \ "http://127.0.0.1:8080/1.0/kb/accounts//paymentMethods?isDefault=true" ---- ++ +Expected result: HTTP `201` and a response containing a `paymentMethodId`. -5. Create an https://apidocs.killbill.io/invoice#create-external-charge-s[external charge] on the account. +. Create an https://apidocs.killbill.io/invoice#create-external-charge-s[external charge] on the account. -6. 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). +. 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 +== Integration -In order to use the Braintree plugin, follow the steps given below: +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: +. Ensure that the plugin is installed and configured as explained above. +. Invoke the `BraintreeTokenServlet` to obtain a token: ++ [source, bash] ---- curl -v \ @@ -151,44 +155,13 @@ curl -v \ -H "X-Killbill-Comment: demo" \ "http://localhost:8080/plugins/killbill-braintree/clientToken" ---- ++ +Expected result: HTTP `200` and a client token payload. -3. 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. - -4. https://developer.paypal.com/braintree/docs/guides/customers[Create a customer] in Braintree. Save the **Customer ID** generated for future reference (it should be something like **620594365**). +. 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. -5. https://apidocs.killbill.io/account#create-an-account[Create] a Kill Bill account. Save the **accountId** for further use. +. Complete steps 2-4 from <> 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. -6. https://apidocs.killbill.io/account#add-a-payment-method[Create] a payment method in Kill Bill using the 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": "xxx" - }, - { - "key": "bt_customer_id", - "value": "xxx" - } - ] - } - }' \ - "http://127.0.0.1:8080/1.0/kb/accounts//paymentMethods?isDefault=true" ----- - -7. Use the `paymentMethodId` to charge the customer as required. +. 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]. - -