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..42bcd642d --- /dev/null +++ b/userguide/tutorials/braintree-plugin.adoc @@ -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= +---- + +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 + +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 <> 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: + +++++ +
+ +
+ +
+
+++++ + + +[[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//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 <> 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].