You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Plugin to use [Braintree](https://www.braintreepayments.com/) as a gateway.
4
5
6
+
A full end-to-end integration demo is available [here](https://github.com/killbill/killbill-braintree-demo).
7
+
5
8
## Kill Bill compatibility
6
9
-----------------------
7
10
@@ -12,7 +15,14 @@ Plugin to use [Braintree](https://www.braintreepayments.com/) as a gateway.
12
15
13
16
## Requirements
14
17
15
-
• An active Braintree account is required for using the plugin. A Braintree Sandbox account may be used for testing purposes.
18
+
* An active Braintree account is required for using the plugin. A Braintree sandbox account may be used for testing purposes.
19
+
* The plugin needs a database. The latest version of the schema can be found [here](https://github.com/killbill/killbill-braintree/tree/master/src/main/resources).
1. The plugin requires that the killbill database includes some additional tables. Connect to the database and execute the ddl.sql file included to create these required tables.
35
+
## Setup
28
36
29
-
2. Go to your Braintree account and obtain the following values:
37
+
In order to use the plugin, Braintree credentials are required. These can be obtained as explained below:
30
38
31
-
* merchantId
32
-
* publicKey
33
-
* privateKey
39
+
1. Create a new Braintree sandbox account by signing up [here](https://www.braintreepayments.com/sandbox).
40
+
2. Login to your account and obtain **Merchant Id**, **Public key**, and **Private key**. See [Braintree - Gateway Credentials](https://articles.braintreepayments.com/control-panel/important-gateway-credentials) for more information about retrieving these values from your account.
34
41
35
-
See [Braintree - Gateway Credentials](https://articles.braintreepayments.com/control-panel/important-gateway-credentials) for more information regarding how to retrieve these values from your account.
42
+
## Configuration
36
43
37
-
3. Add the Braintree gateway credentials as global properties in the killbill.properties file:
44
+
Configure the plugin with the Braintree credentials obtained above as follows:
For the btEnvironment property, use 'sandbox' only for testing with a Braintree Sandbox account. Other possible values include 'development', 'qa', and 'production'. See Braintree documentation for details.
47
-
48
-
Note that these four properties can also be set using the following environment variables:
61
+
Alternatively, you can add the above properties to the `killbill.properties` as explained in the [Kill Bill configuration guide](https://docs.killbill.io/latest/userguide_configuration.html) or set the following environment variables:
49
62
50
63
```bash
51
64
BRAINTREE_ENVIRONMENT
@@ -54,53 +67,149 @@ BRAINTREE_PUBLIC_KEY
54
67
BRAINTREE_PRIVATE_KEY
55
68
```
56
69
57
-
Since unit tests run isolated from the KillBill environment, they can only execute properly if the credentials are set using environment variables. The Braintree plugin on the other hand will attempt to load the credentials from the properties file first, and fallback to the environment variables as a second option only if the properties are not found in the file.
70
+
Some important notes:
71
+
72
+
* Use `btEnvironment=sandbox` only for when a sandbox account is used. Other possible values include **development**, **qa**, and **production**. See Braintree documentation for details.
73
+
* The plugin attempts to load the credentials either from the per-tenant configuration or the Kill Bill properties file while the unit tests require the properties to be set as environment variables.
74
+
* In order to facilitate automated testing, you should disable all fraud detection within your sandbox account. These can generate gateway rejection errors when processing multiple test transactions. In particular make sure to disable [Duplicate Transaction Checking](https://articles.braintreepayments.com/control-panel/transactions/duplicate-checking#configuring-duplicate-transaction-checking).
58
75
59
-
4. In order to facilitate automated testing, you should disable all fraud detection within your Braintree Sandbox account. These can generate gateway rejection errors when processing multiple test transactions. In particular make sure to disable [Duplicate Transaction Checking](https://articles.braintreepayments.com/control-panel/transactions/duplicate-checking#configuring-duplicate-transaction-checking).
76
+
## Testing
60
77
61
-
Once these properties are configured and the plugin restarted it will be ready to be used.
78
+
1. Ensure that the plugin is installed and configured as explained above.
62
79
63
-
For more information regarding killbill properties see [Kill Bill configuration guide](https://docs.killbill.io/latest/userguide_configuration.html).
80
+
2.[Create a customer](https://developer.paypal.com/braintree/articles/control-panel/vault/create) in Braintree with [test card details](https://developer.paypal.com/braintree/docs/reference/general/testing#valid-card-numbers). Save the **Customer ID** generated for future reference (it should be something like **620594365**).
64
81
65
-
## Overview
82
+
3.[Create](https://killbill.github.io/slate/?shell#account-create-an-account) a Kill Bill account. Save the **accountId** for further use.
66
83
67
-
The plugin generates a token for the client by means of a servlet, the client uses this token to send payment information to Braintree in exchange for a nonce. The nonce is used by the KillBill Braintree plugin to create payment methods, or to perform a one-time purchases without the need to vault the payment method. If the nonce is used to create the payment method, then subsequent transactions that use that payment method will use the payment method token instead of the nonce, which becomes invalid once used for the payment method creation.
84
+
4. Create a payment method in Kill Bill using a [fake valid nonce](https://developer.paypal.com/braintree/docs/reference/general/testing#payment-method-nonces) and the braintree customer id as follows:
5. Create an [external charge](https://killbill.github.io/slate/#invoice-create-external-charge-s) on the account.
113
+
114
+
6. Use the `paymentMethodId` to [trigger payment](https://killbill.github.io/slate/#account-trigger-a-payment-for-all-unpaid-invoices) (required only if the `paymentMethodId` is not set as the default payment).
115
+
116
+
## Plugin Internals
117
+
118
+
The plugin generates a token for the client by means of a [servlet](https://github.com/killbill/killbill-braintree/blob/f71ecc98ee6924aa216aa10200027d21640b50f0/src/main/java/org/killbill/billing/plugin/braintree/core/resources/BraintreeTokenServlet.java). The client uses this token to send payment information to Braintree in exchange for a nonce. The nonce is used by the plugin to create a payment method in Kill Bill. Refer to the [Braintree documentation](https://developer.paypal.com/braintree/docs/start/overview) to know more.
68
119
69
120
Payment methods that are supported include:
70
121
71
122
* Credit Card (with or without 3D Secure)
72
123
* PayPal
73
124
* ACH
74
125
75
-
Note that most of the differences in processing these payment methods are managed in the client side, and the nonce received by the backend will be handled in the same manner, with only some small differences.
126
+
Note that most of the differences in processing these payment methods are managed on the client side, and the nonce received by the backend is handled in the same manner, with only some small differences.
76
127
77
-
Note that when creating payment methods from the client at least the following properties must be included for the plugin to work correctly:
128
+
## Integration
78
129
79
-
* bt_nonce: Payment method nonce received from Braintree.
80
-
* bt_customer_id: The customer ID assigned to the customer in Braintree's vault. Only required if not already present as an account Custom Field, if provided it will be set as Custom Field.
81
-
* payment_method_type: The type of payment method that is being created. Possible values include CARD, PAYPAL or ACH. These values are case insensitive. Not to be confused with Braintree's payment instrument type, which includes subdivisions of these three general types.
130
+
In order to use the Braintree plugin, follow the steps given below:
82
131
83
-
### Payment methods sync
132
+
1. Ensure that the plugin is installed and configured as explained above.
84
133
85
-
If you are already storing payment methods in Braintree (or if you want to migrate from another billing system and already have customers in Braintree), the flow to set up Kill Bill accounts is as follows:
134
+
2. Invoke the `BraintreeTokenServlet` to obtain a token:
86
135
87
-
1. Create a Kill Bill account
88
-
2. Attach the custom field `BRAINTREE_CUSTOMER_ID` to the Kill Bill account. The custom field value should be the Braintree customer id
3. Use the [Braintree Drop-in](https://developer.paypal.com/braintree/docs/start/drop-in) implementation to gather the customer's payment details and obtain a payment nonce.
150
+
151
+
4.[Create a customer](https://developer.paypal.com/braintree/docs/guides/customers) in Braintree. Save the **Customer ID** generated for future reference (it should be something like **620594365**).
152
+
153
+
5.[Create](https://killbill.github.io/slate/?shell#account-create-an-account) a Kill Bill account. Save the **accountId** for further use.
154
+
155
+
6. Create a payment method in Kill Bill using the nonce and the braintree customer id as follows:
7. Use the `paymentMethodId` to charge the customer as required.
184
+
185
+
A full end-to-end integration demo that demonstrates Braintree integration is available [here](https://github.com/killbill/killbill-braintree-demo).
186
+
187
+
188
+
## Payment methods sync
189
+
190
+
If you are already storing payment methods in Braintree (or if you want to migrate from another billing system and already have customers in Braintree), the flow to set up Kill Bill accounts is as follows:
191
+
192
+
1.[Create](https://killbill.github.io/slate/?shell#account-create-an-account) a Kill Bill account.
193
+
194
+
2. Attach the custom field `BRAINTREE_CUSTOMER_ID` to the Kill Bill account. The custom field value should be the Braintree customer id:
0 commit comments