View on GitHub

lightrail-stripe-java

Lightrail Integration with Stripe

Lightrail Stripe Integration Library

Lightrail is a modern platform for digital account credits, gift cards, promotions, and points —to learn more, visit Lightrail. The Lightrail Stripe integration provides a client library for developers to easily use Lightrail alongside Stripe. This library is based on the Lightrail Java Client Library.

If you are looking for specific use-cases or other languages, check out the Integrations section of the Lightrail API documentation.

Features

Usage

Order Checkout Using StripeLightrailSplitTenderCharge

TheStripeLightrailSplitTenderCharge class resembles the interface of a Stripe Charge class and transparently splits the transaction between Lightrail and Stripe. The Lightrail parameter could be one of the following:

The Stripe parameter could be:

Here is a simple example:

//this is your order
int orderTotal = 7505;
String orderCurrency = "USD";

//set up your API keys
Stripe.apiKey = "...";
Lightrail.apiKey = "...";

String stripeToken = "...";
String shopperId = "..."; //customer's identifier in your system.

Map<String, Object> params = new HashMap<String, Object>();
params.put("amount", orderTotal);
params.put("currency", orderCurrency);
params.put("source", stripeToken);
params.put("shopperId", shopperId);

SimulatedStripeLightrailSplitTenderCharge simulatedCharge = StripeLightrailSplitTenderCharge.simulate(params);

int creditCardShare = simulatedCharge.getStripeShare();
int accountShare = simulatedCharge.getLightrailShare();
System.out.println(
  String.format("Will charge %s%s on the account card and %s%s on the credit card..",
                orderCurrency, 
                accountShare, 
                orderCurrency, 
                creditCardShare));

StripeLightrailSplitTenderCharge committedCharge = simulatedCharge.commit();

If you do not provide any Lightrail parameters, the entire transaction will be charged to Stripe. Similarly, if you do not provide any Stripe parameters, the library will attempt to charge the entire transaction to Lightrail. In that case, if the value of the Card is not enough to cover the entire transaction amount, you will receive a BadParameterException stating that you must provide a Stripe parameter for this transaction.

When both of Lightrail and Stripe parameters are provided, the library will try to split the payment, in such a way that Lightrail contributes to the payment to the maximum possible extent. This usually means:

The simulate() method returns a SimulatedStripeLightrailSplitTenderCharge object which demonstrates the intended plan for splitting the transaction between Lightrail and Stripe. You can use this object for showing the summary of the payment to the user to confirm. After the user confirms the payment breakdown, call the commit method to finalize the transaction.

If you want to specify the breakdown of the split-tender manually (for example in cases where the customer gets to specify how much from their account they would like to spend in the transaction), you can use the following method:

String stripeToken = "...";
String shopperId = "..."; //customer's identifier in your system.

int stripeShare = ...; //specify the breakdown manually
int lightrailShare = ...;

Map<String, Object> params = new HashMap<String, Object>();
params.put("amount", stripeShare + lightrailShare);
params.put("currency", "USD");
params.put("source", stripeToken);
params.put("shopperId", shopperId);
StripeLightrailSplitTenderCharge.create(params, stripeShare, lightrailShare);

Order Checkout Using CheckoutWithStripeAndLightrail

This class provides a wrapper around StripeLightrailSplitTenderCharge with a more straightforward interface for developers who are not familiar with Stripe’s Java library.

//this is your order
int total = 7505;
String currency = "USD";

//set up your API keys
Stripe.apiKey = "...";
Lightrail.apiKey = "...";

//get the stripe token and the gift code
String stripeToken = "...";
String shopperId = "..."; //customer's identifier in your system.
CheckoutWithStripeAndLightrail checkout = new CheckoutWithStripeAndLightrail(total, currency);
checkoutWithGiftCode.useLightrailShopperId(shopperId);
//or: checkoutWithGiftCode.useLightrailContact("...");
//or: checkoutWithGiftCode.useLightrailCardId("...");
//or: checkoutWithGiftCode.useLightrailGiftCode("...");

checkoutWithGiftCode.useStripeToken(stripeToken);
//or: checkoutWithGiftCode.useStripeCustomer("...");

SimulatedStripeLightrailSplitTenderCharge simulatedCharge = checkoutWithGiftCode.simulate();
int creditCardShare = simulatedCharge.getStripeShare();
int accountShare = simulatedCharge.getLightrailShare();

System.out.println(
  String.format("Will charge %s%s on the account card and %s%s on the credit card.", 
                orderCurrency,
                accountShare,
                orderCurrency,
                creditCardShare));

StripeLightrailSplitTenderCharge committedCharge = simulatedCharge.commit();

Installation

Maven

You can add this library as a dependency in your maven POM file as:

<dependency>
  <groupId>com.lightrail</groupId>
  <artifactId>lightrail-stripe-client</artifactId>
  <version>2.0.1</version>
</dependency>

Build And Test

You can build this library from source using maven. Assuming that maven is installed and configured in your environment, you can simply download or clone the source and invoke:

$ mvn clean package -DskipTests

Note that this will skip the unit tests. In order to run the tests, you will need to set the following parameters in the property file _test-config.property. A template is provided in test-config-template.properties:

Requirements

This library requires Java 1.7 or later.

Dependencies

The only dependency of this library are lightrail-client and stripe-java.

<dependency>
  <groupId>com.lightrail</groupId>
  <artifactId>lightrail-client</artifactId>
  <version>2.0.1-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>com.stripe</groupId>
  <artifactId>stripe-java</artifactId>
  <version>5.6.0</version>
</dependency>

If your project already depends on a different version of the Stripe library, make sure the versions are compatible. We will ensure to periodically update the dependencies to the latest version.

The following dependency is also necessary if you want to run the unit tests.

<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <version>4.12</version>
  <scope>test</scope>
</dependency>

Changelog

2.0.1

2.0.0

1.1.0

1.0.1