This guide is for developers seeking to get a better understanding of the principles of our Loyalty and Gift-Card / Payments APIs (documentation is here).
This guide will gradually be added to as time permits, but this is meant to provide some extra guidance and is not a comprehensive tutorial. Tweaking and fiddling is strongly encouraged.
Before you begin
- You must already have API or Developer Partner access. If you are a customer (or a developer working specifically with an existing Lightspeed customer) you will need to contact your Account Manager to be given API access. If you are an approved partner you should already have API access.
Creating your Application in Back Office
Assuming you have been given API and Developer access, the first step is to create your application itself. This can be done by going to Back Office and going to Integrations, then "Create a new Integration"
You'll then see this screen where you can get your Client ID, Client Secret, and so on.
Importantly, you will also see tabs for Loyalty and Payments. (Gift Card functions are available under Payments).
Important Note: Keep your Client Secret recorded somewhere and do not lose it. Our Support Team are not able to retrieve this for you.
Once you have your ClientID and Client Secret, you will need to generate an OAuth token. If you do not have a working service to create one, this guide will show you how to use a temporary webhook service to generate one that will work for now.
Be aware that loyalty and Payments will not work properly unless your application has a registered Refresh token. You can still use Basic Authentication credentials to make API calls (although this is not recommended) but the actual Payments and Loyalty system themselves will not activate without that token being in our database.
Using Postman to act as a Mock Server
An important distinction with how our Payments and Loyalty APIs work compared to our other endpoints is these do not generally work with a simple direct feed into our server.
The POS register will make queries to your service and expect data to be returned in a certain format which is defined in the documentation. As such, without a mock server to test these APIs you will not get very far.
One method is to simply have a raw JSON file with the dummy data we provide in the documentation, as long as it is accessible the API will be able to make calls to those endpoints. But obviously this isn't practical for testing and development.
So for this tutorial we will use Postman's mock server system.
A full course on Postman and it's mock server is beyond the scope of this tutorial but the above link should cover most questions.
This JSON file can be imported as a collection for the purpose of this demonstration.
Once the file is imported into Postman your screen should look like this:
Click the three dots next to the collection title and clock 'Mock Collection' to create a mock server.
Give your Mock server a name (call it anything you want) but ensure that "Save the mock server URL as an environment variable" is ticked or the collection will not work.
Click the "Create Mock Server" button on the bottom right of the screen, and Postman will then give you a URL that you can use. In this example the URL is https://723db7ea-e12c-4da1-81b4-e14e2eed9c65.mock.pstmn.io - whenever you see this URL being used in this tutorial, please replace it with your own.
The collection you imported will already have sample data available, so before we cover those off let's skip to setting up the endpoints for your integration in Back Office.
Then on the Payments tab:
Click Save, then go into POS mode on your Register and then Sync your register.
Testing our Mock API
We should now be able to test our mock integration.
The first thing to do is make sure our payment type even appears.
Generate a dummy order, click Checkout and ensure you can see the payment type you named.
If it isn't there, go to Back Office, double check the settings are there. If they are, go back to POS and re-sync your POS.
If it IS there, as per the below screenshot, notice that I have my POS and Postman side by side. (Also note that in Postman the URL matches the checkout URL we set in BackOffice earlier...)
Adjust the payload amount to be what you want the mock server to return when this payment is processed and click save, then process the transaction by clicking your payment button.
(Need this to be a gift card? Set "Require Reference ID" in your Back Office, and add an example to match up with your ID request in Postman, and you have a Gift Card!)
The test data supplied won't differentiate gift card numbers, to do that simply create extra "examples" in Postman to match up to the reference IDs the system will send you as per the documentation.
But to confirm the API call works, just go to Menu -> Add-Ons Gift Card
Select your Payment Type name
Click Check Balance and the provided balance will match the JSON payload in your sample collection.
Customer Search and Reward Lookup
I heavily recommend spending some time playing with this one, the API calls here are quite sensitive. When making examples, ensure there is a "fallback" payload as the search function in POS will crash if it receives anything other than a JSON payload.
The default payload provided in the demonstration collection is for David Kent.
The customer search and reward lookup work in tandem.
The "redeem_url" attached to the rewards needs to attach to an endpoint that fires off an API call that updates the order with the actions your reward needs to take.
Updating Payments on orders that are NOT created by your application
This needs to be subject to review from the partnerships team, but we can enable a flag that will allow your application to be used to pay for orders that your API did not create. Please contact email@example.com should you require this functionality.