Braintree plugin documentation

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

userguide/tutorials/braintree-plugin.adoc

@@ -0,0 +1,194 @@
+= 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
+
+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.|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
+----
+
+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 TBB
+
+[[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
+
+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/<ACCOUNT_ID>/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/<ACCOUNT_ID>/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].
+
+