Skip to content

Commit 534242b

Browse files
sbrossiesbrossie
authored
Merge pull request #662 from reshmabidikar/braintree-doc
Braintree plugin documentation
2 parents fed685f + 2bea148 commit 534242b

2 files changed

Lines changed: 170 additions & 0 deletions

File tree

‎html5/_main_toc.html.slim‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,9 @@ nav.sidebar-nav
184184
li
185185
a.nav-link href="/latest/avatax-plugin.html"
186186
| AvaTax Plugin
187+
li
188+
a.nav-link href="/latest/braintree-plugin.html"
189+
| Braintree Plugin
187190
li
188191
a.nav-link href="/latest/notification_plugin.html"
189192
| Notification Plugins

‎userguide/tutorials/braintree-plugin.adoc‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
= Braintree Plugin
2+
3+
The https://github.com/killbill/killbill-braintree[Braintree Plugin] is a Kill Bill payment plugin for the https://www.braintreepayments.com/[Braintree payment gateway].
4+
5+
== Prerequisites
6+
7+
* 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__].
8+
* 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.
9+
* 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].
10+
11+
== Overview
12+
13+
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.
14+
15+
== Plugin Installation
16+
17+
You can install the plugin as explained in the https://docs.killbill.io/latest/plugin_installation#_plugin_installation[Plugin Installation Guide].
18+
19+
For example, to install the plugin via https://github.com/killbill/killbill-cloud/blob/master/kpm[KPM], you can run the following command:
20+
21+
[source,bash]
22+
----
23+
kpm install_java_plugin braintree-plugin --destination=<path_to_install_plugin>
24+
----
25+
26+
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.
27+
28+
== Database Configuration
29+
30+
The Braintree plugin requires some additional database tables. To create these tables, please follow the steps given below:
31+
32+
. Connect to the Kill Bill database.
33+
34+
. Run the https://github.com/killbill/killbill-braintree/blob/master/src/main/resources/ddl.sql[Braintree Plugin DDL].
35+
36+
== Plugin Configuration
37+
38+
The Braintree plugin requires the following properties:
39+
40+
[options="header",cols="1,1,1,1"]
41+
|===
42+
|Property Name |Description | Required|Default Value
43+
//----------------------
44+
|org.killbill.billing.plugin.braintree.btEnvironment|The Braintree environment to use.|Yes|-
45+
|org.killbill.billing.plugin.braintree.btMerchantId|Unique Braintree merchant identifier that tells the plugin which merchant account to process transactions under.|Yes|-
46+
|org.killbill.billing.plugin.braintree.btPublicKey|The public API key from your Braintree account used to authenticate API calls.|Yes|-
47+
|org.killbill.billing.plugin.braintree.btPrivateKey|The private API key from your Braintree account used alongside the public key to authenticate API calls.|Yes|-
48+
|===
49+
50+
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:
51+
52+
[source, bash]
53+
----
54+
curl -v \
55+
-X POST \
56+
-u admin:password \
57+
-H 'X-Killbill-ApiKey: bob' \
58+
-H 'X-Killbill-ApiSecret: lazar' \
59+
-H 'X-Killbill-CreatedBy: admin' \
60+
-H 'Content-Type: text/plain' \
61+
-d 'org.killbill.billing.plugin.braintree.btEnvironment=sandbox
62+
org.killbill.billing.plugin.braintree.btMerchantId=xxx
63+
org.killbill.billing.plugin.braintree.btPublicKey=xxx
64+
org.killbill.billing.plugin.braintree.btPrivateKey=xxx' \
65+
http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-braintree
66+
----
67+
68+
Expected result: HTTP `201`/`204` and no validation errors in the response.
69+
70+
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.
71+
72+
// == Kaui Integration TBD
73+
74+
[[aviate_integration]]
75+
== Aviate Integration
76+
77+
You can use the https://aviate.killbill.io/home[Aviate UI] to install/configure the plugin. Refer to the following demo:
78+
79+
++++
80+
<div>
81+
<script async src="https://js.storylane.io/js/v2/storylane.js"></script>
82+
<div class="sl-embed" style="position:relative;padding-bottom:calc(49.85% + 25px);width:100%;height:0;transform:scale(1)">
83+
<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>
84+
</div>
85+
</div>
86+
++++
87+
88+
89+
[[testing_the_plugin]]
90+
== Testing the Plugin
91+
92+
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.
93+
94+
You can follow the steps given below to test the plugin:
95+
96+
. Ensure that the plugin is installed and configured as explained above.
97+
98+
. 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**).
99+
100+
. https://apidocs.killbill.io/account#create-an-account[Create] a Kill Bill account. Save the **accountId** for further use.
101+
102+
. 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:
103+
+
104+
[source, bash]
105+
----
106+
curl -v \
107+
-u admin:password \
108+
-H "X-Killbill-ApiKey: bob" \
109+
-H "X-Killbill-ApiSecret: lazar" \
110+
-H "Content-Type: application/json" \
111+
-H "X-Killbill-CreatedBy: demo" \
112+
-X POST \
113+
--data-binary '{
114+
"pluginName": "killbill-braintree",
115+
"pluginInfo": {
116+
"properties": [
117+
{
118+
"key": "bt_nonce",
119+
"value": "fake-valid-nonce"
120+
},
121+
{
122+
"key": "bt_customer_id",
123+
"value": "xxx"
124+
}
125+
]
126+
}
127+
}' \
128+
"http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/paymentMethods?isDefault=true"
129+
----
130+
+
131+
Expected result: HTTP `201` and a response containing a `paymentMethodId`.
132+
133+
. Create an https://apidocs.killbill.io/invoice#create-external-charge-s[external charge] on the account.
134+
135+
. 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).
136+
137+
== Integration
138+
139+
In order to use the Braintree plugin in your application, follow the steps given below:
140+
141+
. Ensure that the plugin is installed and configured as explained above.
142+
143+
. Invoke the `BraintreeTokenServlet` to obtain a token:
144+
+
145+
[source, bash]
146+
----
147+
curl -v \
148+
-u admin:password \
149+
-H "X-Killbill-ApiKey: bob" \
150+
-H "X-Killbill-ApiSecret: lazar" \
151+
-H "Content-Type: application/json" \
152+
-H "Accept: application/json" \
153+
-H "X-Killbill-CreatedBy: demo" \
154+
-H "X-Killbill-Reason: demo" \
155+
-H "X-Killbill-Comment: demo" \
156+
"http://localhost:8080/plugins/killbill-braintree/clientToken"
157+
----
158+
+
159+
Expected result: HTTP `200` and a client token payload.
160+
161+
. 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.
162+
163+
. 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.
164+
165+
. Use the `paymentMethodId` to charge the customer as required.
166+
167+
A full end-to-end integration demo that demonstrates Braintree integration is available https://github.com/killbill/killbill-braintree-demo[here].

0 commit comments

Comments
 (0)