Lightrail Client for PHP
This client is for Lightrail v1. If you're not sure what that is you probably want the v2 library lightrail-client-php-v2.
The following features are supported in this version:
- Account credits: create, retrieve, balance-check, and create/simulate transactions
- Contacts: create, retrieve, retrieve contact's account card
Note that the Lightrail API supports many other features and we are still working on covering them in this library. For a complete list of Lightrail API features check out the Lightrail API documentation.
For a sample project using this library, check out the Lightrail Stripe Sample PHP Web App.
Before using this client, you'll need to configure it to use your API key. You can find this in the Lightrail web app -- go to your account settings, then click 'API keys' and 'Generate Key.'
\Lightrail\Lightrail::$apiKey = <LIGHTRAIL_API_KEY>;
You can add this library as a dependency to your project using
composer require lightrail/lightrail
Use Case: Account Credits Powered by Lightrail
The remainder of this document is a quick demonstration of implementing account credits powered by Lightrail using this library. It will assume familiarity with the API and some core concepts, which are discussed in detail in the 'Powering Account Credits' section of the API documentation.
Creating a New Contact
To create a new Contact, you need to provide a client-side unique identifier known as the
userSuppliedId. This is a per-endpoint unique identifier used to ensure idempotence (meaning that if the same request is issued more than once, it will not result in repeated actions). Typically this is a customer ID generated by your CRM. Note that the terms
userSuppliedId for Contacts are interchangeable (the Lightrail server will store the value as a
userSuppliedId but you can refer to it as a
Optionally, you can also provide an
lastName. Here is a sample call:
$contactParams = array( 'shopperId' => 'cust-a95a09', 'email' => 'email@example.com' ); $contact = \Lightrail\LightrailContact::create($params);
The return value will be a
LightrailContact object, which will include both the
shopperId you provided (as
userSuppliedId) and a server-generated
contactId. You can choose to save either value to retrieve the contact later:
\Lightrail\LightrailContact: ( 'contactId' => 'contact-0s459jy6h56', 'userSuppliedId' => 'cust-a95a09', 'email' => 'firstname.lastname@example.org' )
Retrieving a Contact
You can retrieve a Contact by its
shopperId or its
contactId. The response to this call will be a
LightrailContact object similar to the one shown above.
You can create an account for a contact based on their
shopperId (identifier generated by your e-commerce system) or based on their
contactId (generated by Lightrail). You must also specify the currency that the account will be in, and provide a
userSuppliedId, a unique identifier from your own system. Since each Contact can have only up to one Account Card per currency, you can add the currency as a suffix to the
userSuppliedId you provided for the Contact.
You may optionally include an
initialValue for the account. If provided, this must be a positive integer in the smallest currency unit (for example,
500 is 5 USD).
$contact = \Lightrail\LightrailContact::retrieveByShopperId('cust-a95a09'); $accountParams = array( 'shopperId' => 'cust-a95a09', // alternatively use the Lightrail generated identifier: 'contactId' => 'contact-0s459jy6h56' 'userSuppliedId' => 'cust-a95a09-usd-account', 'currency' => 'USD', 'initialValue' => 500 ); $account = \Lightrail\LightrailAccount::createAccountCard();
The return value will be a
LightrailCard object, which will include both the account card's
userSuppliedId that you provided and a Lightrail-generated
cardId which you can persist and use to retrieve the account card later, as well as several other details:
\Lightrail\LightrailCard: ( 'cardId' => 'card-4358huf98r', 'userSuppliedId' => 'cust-a95a09-usd-account', 'currency' => 'USD', // output simplified for readability )
Funding and Charging
To fund or charge an account, you can once again use either the
contactId (generated by Lightrail) or the
shopperId (generated by your e-commerce system) to identify the customer account that you wish to transact against.
You must additionally pass in the following:
valueof the transaction: a positive
valuewill add funds to the account, while a negative
valuewill post a charge to the account. This amount must be in the smallest currency unit (e.g.,
500for 5 USD)
currencythat the transaction is in (note that Lightrail does not handle currency conversion and the contact must have an account in the corresponding currency)
userSuppliedId, which is a unique transaction identifier to ensure idempotence (for example, the order ID from your e-commerce system)
$transactionParams = array( 'shopperId' => 'cust-a95a09', 'currency' => 'USD', 'value' => -350, 'userSuppliedId' => 'order-a90h09a509gaj00-a4' ); \Lightrail\LightrailAccount::createTransaction($transactionParams);
The return value is a
LightrailTransaction which includes the full details of the transaction, including both the
userSuppliedId you provided and a server-generated
transactionId you can later use to retrieve the transaction again:
\Lightrail\LightrailTransaction: ( 'transactionId' => 'transaction-4358huf98r', 'userSuppliedId' => 'order-a90h09a509gaj00-a4', 'transactionType' => 'DRAWDOWN', 'value' => -350, 'currency' => 'USD', // output simplified for readability )
Transaction Simulation and Balance Checking
Before attempting to post a transaction, you may wish to do a transaction simulation to find out whether or not the account has enough funds. In the case of insufficient funds, this can also tell you the maximum value for which the transaction would be successful. For example, if you simulate a $35 drawdown Transaction, the method can tell you that it would be successful if it were only for $20.
The parameters for this method call are almost identical to those for posting a transaction. To get the maximum value, add
nsf: false to your transaction parameters:
$simulationParams = array( 'shopperId' => 'cust-a95a09', 'currency' => 'USD', 'value' => -6500, 'userSuppliedId' => 'order-a90h09a509gaj00-a4', 'nsf' => 'false' ); \Lightrail\LightrailAccount::simulateTransaction($simulationParams);
The response will be similar to the following. Note that this is just a simulation and NOT an actual transaction; for instance, it does not have a
transactionId. The response indicates that for this transaction, the maximum value this account can provide is $55.
\Lightrail\LightrailTransaction: ( 'value' => -5500, 'userSuppliedId' => 'order-a90h09a509gaj00-a4', 'transactionType' => 'DRAWDOWN', 'currency' => USD 'transactionBreakdown' => ( ( 'value' => -500 'valueAvailableAfterTransaction' => 0 'valueStoreId' => value-497d783b68fc4b4caa4f12be19112fbd ), ( 'value' => -5000 'valueAvailableAfterTransaction' => 0 'valueStoreId' => value-4eee14b03d454a6aa514c87e1268639d ) ), 'transactionId' => null, // output simplified for readability )
If you are using our Drop-in Gift Card solution, you can use this library to generate shopper tokens for transacting against a customer's account.
A shopper token is generated from a unique customer identifier from your system: this is the same
shopperId or contact
userSuppliedId you would have used when creating the Contact, or you can also use the Lightrail-generated
contactId that comes back in the response when a Contact is created.
\Lightrail\LightrailShopperTokenFactory::generate(array('shopperId' => 'cust-a95a09')); \Lightrail\LightrailShopperTokenFactory::generate(array('contactId' => 'contact-0s459jy6h56'));
You can also pass in an optional second argument specifying the token's validity in seconds:
\Lightrail\LightrailShopperTokenFactory::generate(array('shopperId' => 'cust-a95a09', 600));
Note that if you haven't yet created a Contact record, some functions that use the generated shopper token will create one for you automatically based solely on the
shopperId you provide - ie Account creation. If you want extra information to be associated with the Contact, like their name or email address, you should create the contact first.
IMPORTANT: note that several environment variables are required for the tests to run. After cloning the repo,
composer install dependencies, then copy
.env and fill in the following (or use your preferred way of setting 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_SHARED_SECRET: set this to any string (used to generate shopper tokens).
CARD_ID: this is the
cardIdfor a USD card with at least a few dollars on it.
SHOPPER_ID: the userSuppliedId for a Lightrail contact with a USD account with a few dollars in it.
CONTACT_ID: the Lightrail-generated contactId for the same contact.
Then you can run
Bug reports and pull requests are welcome on GitHub at https://github.com/Giftbit/lightrail-client-php.
After pushing changes to Github, tag a new release. You can do this via the web interface or through the command line:
git tag -a vX.X.X -m "Tag message or title" git push origin vX.X.X
Then log into packagist.org and click "Update" on the
lightrail/lightrail package (you must be logged in as the Lightrail user).
This library is available as open source under the terms of the MIT License.