npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

lightrail-stripe

v1.0.1

Published

A Javascript and Typescript library for creating Lightrail-Stripe integrated applications.

Downloads

19

Readme

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.