Plugin to use Stripe as a gateway.
A full end-to-end integration demo is available here.
| Plugin version | Kill Bill version | Stripe version |
|---|---|---|
| 1.x.y | 0.14.z | 2015-02-18 |
| 3.x.y | 0.16.z | 2015-02-18 |
| 4.x.y | 0.18.z | 2015-02-18 |
| 5.x.y | 0.19.z | 2015-02-18 |
| 6.x.y | 0.20.z | 2015-02-18 |
| 7.0.y | 0.22.z | 2019-12-03 |
| 7.1.y | 0.22.z | 2019-12-03 |
| 7.2.y | 0.22.z | 2020-08-27 |
| 7.3.y | 0.22.z | 2020-08-27 |
| 8.0.y | 0.24.z | 2020-08-27 |
- Starting with 7.3.0, the Setup Intents API is used to validate and store payment instruments, instead of the Payment Intents API.
- We've upgraded numerous dependencies in 7.1.x (required for Java 11 support).
The plugin needs a database. The latest version of the schema can be found here.
Locally:
kpm install_java_plugin stripe --from-source-file target/stripe-plugin-*-SNAPSHOT.jar --destination /var/tmp/bundles
Go to https://dashboard.stripe.com/test/apikeys and copy your Secret key.
Then, go to the Kaui plugin configuration page (/admin_tenants/1?active_tab=PluginConfig), and configure the stripe plugin with your key:
org.killbill.billing.plugin.stripe.apiKey=sk_test_XXXAlternatively, you can upload the configuration directly:
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.stripe.apiKey=sk_test_XXX
org.killbill.billing.plugin.stripe.chargeDescription=YYY
org.killbill.billing.plugin.stripe.chargeStatementDescriptor=ZZZ' \
http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-stripeTo charge a payment instrument (card, bank account, etc.), you first need to collect the payment instrument details in Stripe and create an associated payment method in Kill Bill.
Use this method if you don't want to generate your own form to tokenize cards.
To save credit cards using Stripe Checkout:
- Create a Kill Bill account
- Call
/plugins/killbill-stripe/checkoutto generate a Session:
curl -v \
-X POST \
-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://127.0.0.1:8080/plugins/killbill-stripe/checkout?kbAccountId=<KB_ACCOUNT_ID>"The default is to only allow credit cards. If you want to enable sepa direct debit payments, you need to include the paymentMethodTypes option, i.e. change the URL of your POST request
to http://127.0.0.1:8080/plugins/killbill-stripe/checkout?kbAccountId=<KB_ACCOUNT_ID>&paymentMethodTypes=card&paymentMethodTypes=sepa_debit.
- Redirect the user to the Stripe checkout page. The
sessionIdis returned as part of theformFields(idkey):
stripe.redirectToCheckout({ sessionId: 'cs_test_XXX' });- After entering the credit card or bank account details, the payment method will be available in Stripe. Call
addPaymentMethodto store the payment method in Kill Bill:
curl -v \
-X POST \
-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" \
-d "{ \"pluginName\": \"killbill-stripe\"}" \
"http://127.0.0.1:8080/1.0/kb/accounts/<KB_ACCOUNT_ID>/paymentMethods?pluginProperty=sessionId=cs_test_XXX"If you have a token or sources, you can pass it directly to addPaymentMethod in the plugin properties:
curl -v \
-X POST \
-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" \
-d "{ \"pluginName\": \"killbill-stripe\"}" \
"http://127.0.0.1:8080/1.0/kb/accounts/<KB_ACCOUNT_ID>/paymentMethods?pluginProperty=token=tok_XXX"curl -v \
-X POST \
-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" \
-d "{ \"pluginName\": \"killbill-stripe\"}" \
"http://127.0.0.1:8080/1.0/kb/accounts/<KB_ACCOUNT_ID>/paymentMethods?pluginProperty=source=src_XXX"Take a look at kbcmd for a step-by-step walkthrough.
Note: if the token/source is already attached to a customer in Stripe, make sure to first set the STRIPE_CUSTOMER_ID custom field to the account in Kill Bill (see below) before calling addPaymentMethod (in this case, the token will be stored as-is and assumed to be re-usable if you intent to do subsequent payments). Otherwise, the plugin assumes it is a one-time token and will automatically create an associated customer in Stripe attached to this token/source to be able to re-use it (if needed, you can bypass this logic by specifying the createStripeCustomer=false plugin property in the addPaymentMethod call).
If you are using Stripe Elements or storing payment methods in Stripe via any other way (or if you want to migrate from another billing system and already have customers in Stripe), the flow to setup Kill Bill accounts is as follows:
- Create a Kill Bill account
- Attach the custom field
STRIPE_CUSTOMER_IDto the Kill Bill account. The custom field value should be the Stripe customer id
curl -v \
-X POST \
-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" \
-d "[ { \"objectType\": \"ACCOUNT\", \"name\": \"STRIPE_CUSTOMER_ID\", \"value\": \"cus_XXXXX\" }]" \
"http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/customFields"- Sync the payment methods from Stripe to Kill Bill:
curl -v \
-X PUT \
-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://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/paymentMethods/refresh"For testing you need to add your Stripe public and private key to src/test/resources/stripe.properties:
org.killbill.billing.plugin.stripe.apiKey=sk_test_XXX
org.killbill.billing.plugin.stripe.publicKey=pk_test_XXX
Kill Bill is the leading Open-Source Subscription Billing & Payments Platform. For more information about the project, go to https://killbill.io/.
![dependabot[bot]](https://avatars.githubusercontent.com/u/49699333?size=120)
