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 in Javascript (Node).

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

Important

This library is in beta mode and may have breaking changes before v1.0.0.

Features

Simple order checkout supporting split-tender transactions with Lightrail redemption alongside a Stripe payment.

Usage

Configuration

Before using this library, you'll need to configure the Lightrail Client to use your API key:

const Lightrail = require('lightrail');
Lightrail.configure({
  apiKey: "a23rtshs4.a245ty56j5st.90ejsirgormt"
})

Split Tender Checkout

A split-tender transaction happens when a transaction is broken down into two (or more) transactions each processed by a different payment methods. In this use-case we will focus on the common case of dividing a transaction between a Lightrail Card (Gift Card or Account Card) and a credit card processed by Stripe. For example, if you are processing a $134.25 transaction and the customer would like to redeem a $30 value from their Gift Card, you need to charge $30 to the Lightrail Card and the remaining $104.25 must be charged to Stripe.

For a sample project using this library, check out the Lightrail Stripe Sample Node Web App.

Creating a Split Tender Transaction

If you already process Stripe payments, the interface for implementing a split tender checkout will be familiar.

You will need the following general parameters:

The total amount of the transaction
The currency of the transaction
A userSuppliedId as a unique transaction identifier to ensure idempotence (meaning that if the same request is issued more than once, it will not result in repeated actions). This is typically the order ID from your ecommerce system.
Optional metadata (the split tender checkout process will not interfere with any metadata or other parameters that you are accustomed to sending to Stripe and will pass them on as they are provided).

For Lightrail, you will need the following parameters. If you need to read more about these check out the Lightrail API Docs:

Your Lightrail apiKey
A Lightrail shopperId (ie a Contact's userSuppliedId) to specify a customer by their shopper ID (generated by your ecommerce system)
The amount that is meant to be covered by Lightrail — the lightrailShare

For Stripe, you will need the following parameters. If you need to read more about these check out the Stripe Docs:

Your Stripe secretKey or a configured Stripe instance
A Stripe token or customerId to specify which credit card you are going to charge via Stripe. Note that based on Stripe's flow you have to either use one of Stripe's browser-side methods to capture the credit card information and exchange it for a token, or use a previously-registered customerId.

const Lightrail = require('lightrail');
Lightrail.configure({
  apiKey: "eyJhbGciOiJIUz.eyJnIjp7Imd1aSI6Imdv.uQR5JntsoZE_ECtIHosX"
})
const LightrailStripe = require("lightrail-stripe");
const Stripe = require("stripe")("sk_Ar32o89fe90ger63j");
 
const splitTenderParams = {
  userSuppliedId:"order-s3xx30",
  amount:6960,
  currency:"USD",
  metadata: {
    cart: {
      total: 6960,
      items: [
        {
          id: "B009L1MF7A",
          quantity: 3,
          unit_price: 2320,
          tags: ["apparel", "outdoor"]
        }
      ]
    }
  },
  shopperId: "customer-ae0a4t6mnx",
  source: "token_visa"
};
 
LightrailStripe.createSplitTenderCharge(
  splitTenderParams, 
  6200, 
  Stripe    // you can also pass in your Stripe key here instead
).then(
  // called asynchronously
);

The return object will have a lightrailTransaction and a stripeCharge containing details of their respective transactions (output simplified for ease of reading):

{ "lightrailTransaction":
   { "value": -6200,
     "userSuppliedId": "order-s3xx30-capture",
     "dateCreated": "2017-11-14T23:59:58.150Z",
     "transactionType": "DRAWDOWN",
     "cardId": "card-c99f0cdf9",
     "currency": "USD",
     "transactionBreakdown": {},
     "transactionId": "transaction-89e0a",
     "parentTransactionId": "transaction-372e2",
     "metadata":
      { "cart": {
          "total": 6960,
          "items": [ {
                    "id": "B009L1MF7A",
                    "quantity": 3,
                    "unit_price": 2320,
                    "tags": ["apparel", "outdoor"]
                  } ]
       },
      "_split_tender_total": 6960,
      "giftbit_initial_transaction_id": "transaction-372e2",
      "_split_tender_partner": "STRIPE",
      "_split_tender_partner_transaction_id": "ch_1BOEJt" } },
  "stripeCharge":
   { "id": "ch_1BOEJt",
     "object": "charge",
     "amount": 760,
     "balance_transaction": "txn_1BOEJtE2",
     "captured": true,
     "created": 1510703997,
     "currency": "usd",
     "metadata":
      { "cart": {
          "total": 6960,
          "items": [ {
                     "id": "B009L1MF7A",
                     "quantity": 3,
                     "unit_price": 2320,
                     "tags": ["apparel", "outdoor"]
                   } ]
        },
       "_split_tender_total": "6960",
       "_split_tender_partner": "LIGHTRAIL",
       "_split_tender_partner_transaction_id": "transaction-89e0a" },
     "outcome":
      { "network_status": "approved_by_network",
        "reason": null,
        "risk_level": "normal",
        "seller_message": "Payment complete.",
        "type": "authorized" },
     "paid": true,
     "source":
      { "id": "card_1BOEJtE2wGcUjQW3iH0pk4Xf",
        "object": "card",
        "brand": "Visa",
        "country": "US",
        "last4": "4242" },
     "status": "succeeded" } }

Note that metadata items have been added to both transactions to ensure transaction traceability.

In the case that the full transaction is covered by Lightrail (ie, lightrailShare is the full transaction amount), the stripeCharge will be null, and vice versa if the full transaction is covered by Stripe.

Development

IMPORTANT: note that several environment variables are required for the tests to run. After cloning the repo, npm install dependencies and set the following (either in a .env file in the root directory or however you prefer to set environment variables):

LIGHTRAIL_API_KEY: find this in to the Lightrail web app -- go to your account settings, then click 'API keys' and 'Generate Key.' Note that for running tests, you should use a test mode key.
LIGHTRAIL_SHOPPER_ID: this is the userSuppliedId of one of your Lightrail Contacts that has a USD Account Card with at least a few dollars on it.
STRIPE_SECRET_KEY: find this in your Stripe dashboard -- note that for running tests, you should use a test mode secret key.

Then you can run npm test.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Giftbit/lightrail-client-javascript.

License

This library is available as open source under the terms of the MIT License.