bLoyal POS Integration Guide - Customer Loyalty Software ......Order Processing (POS Snippets) - Additionally, omni-channel order processing can be easily added to any POS system by

1 of 25 Copyright © 2016-2018 bLoyal.com. All Rights Reserved

bLoyal

POS Application

Integration Guide

Last Updated: December 1, 2016

“Helping you build loyal customers” TM

bLoyal CONFIDENTIAL INFORMATION

This document contains proprietary information and the intellectual property of bLoyal.

This information is confidential and is only available to under a properly executed Non-

Disclosure Agreement (NDA). You are hereby notified that any dissemination, distribution or

copying of this communication is strictly prohibited. If the reader of this document does not have

an NDA in place with bLoyal please notify us immediately by replying to [email protected] or at

877-425-1715 and delete the document from your computer.

Thank You


Table of Contents: 1. Introduction ........................................................................................ 2 2. Application Connector Certification Levels ........................................... 2 3. Integration and API Overview ............................................................. 4

3.1 Key Concepts .......................................................................................................... 4 3.2 Obtaining bLoyal Service URLs ................................................................................... 5 3.3 Generating an Access Key ......................................................................................... 5 3.4 Identifying external entities ....................................................................................... 5 3.5 Web API vs. bLoyal Nuget Packages ........................................................................... 6

4. bLoyal Loyalty GridTM – Backend Data Integration ............................... 8 4.1 Protocol – “Start” and “Close” Integration Batch .......................................................... 8 4.2 Synchronizing Entities .............................................................................................. 9 4.3 Supported Entities.................................................................................................. 11

5. bLoyal Loyalty EngineTM – Promotions and Awards ............................ 12 5.1 In-flow Promotions and Redemptions ....................................................................... 12 5.2 Customer and Subscriber Group Signup (optional) ..................................................... 14

6. POS Snippets – Customer Signup ....................................................... 16 6.1 Launching a POS Snippet ........................................................................................ 16 6.2 Supported POS Snippets ......................................................................................... 17

7. bLoyal Payment EngineTM - Tender Based Redemptions ..................... 18 8. bLoyal Order Processing .................................................................... 20

8.1 POS Snippets ........................................................................................................ 20 8.2 Shipping Charge and Sales Tax ................................................................................ 20 8.3 Inventory Replication ............................................................................................. 21

9. bLoyal Logging (optional) .................................................................. 22 9.1 Protocol – bLoyal Nuget packages ............................................................................ 22 9.2 Protocol – RESTful Web APIs ................................................................................... 23

10. Appendix A: bLoyal API Mappings ...................................................... 24 11. Revision History ................................................................................. 25

1. Introduction

bLoyal is a cloud based customer loyalty and order processing platform that works across channels

and devices. Our goal is to make it easy for you to add bLoyal services to your POS application.

This integration guide describes how to integrate bLoyal with a POS application and describes the

different levels of certification. The guide is intended to provide everything needed to complete the

integration though the SDK samples may prove useful in completing the integration. The SDK

samples can be found here: Support Center Forums.

2. Application Connector Certification Levels

There are three levels of integration for a POS application beyond the “Enabled” scenario.

bLoyal Enabled – A bLoyal enabled integration is one in which the POS system is

integrated with a common processor (e.g. First Data’s Value Link). This provides basic bLoyal functionality without the need for further integration.

bLoyal Backend Certified – A bLoyal backend certified integration is one in which the POS

system is sending Sales Transactions, Products, and Customers to bLoyal via the bLoyal

Grid. A backend certified integration provides a one-way data synchronization from the POS

system to bLoyal where bLoyal accrues benefits and generates awards that can be

https://mysupport.bloyal.com/forums


redeemed via any one of the “disconnected” redemption scenarios provided by bLoyal such as the My Mobile LoyaltyTM application.

bLoyal In-Flow Certified – A bLoyal in-flow certified integration supports bLoyal

promotions and award benefits in-flow of the POS transaction using the bLoyal Loyalty

Engine. The in-flow certified integration also supports the use of bLoyal’s Payment Engine

to enable tender based redemptions. It also builds on the backend certified integration to

provide two-way data synchronization between the POS system and bLoyal using the bLoyal

Grid.

bLoyal Order Processing Certified – A bLoyal order processing certified integration

continues to build on the in-flow certified integration to leverage bLoyal’s order processing capabilities at the POS to enable omni-channel POS shipping and pickup orders.


3. Integration and API Overview

A POS integration includes the following components, depending on the level of certification being

targeted.

bLoyal Backend Certified:

Backend Data Integration – Certain data needs to flow between the POS system and bLoyal.

This can either be a one-way data flow between the POS system and bLoyal or a two-way

data synchronization between each system. This backend data integration is handled using

the bLoyal Loyalty Grid.

bLoyal In-Flow Certified:

Promotions and Awards – Promotions and loyalty awards can be applied in-flow of the

transaction. Promotions and loyalty awards are accessed using the bLoyal Loyalty Engine.

Customer Signup (POS Snippets) - Customers can be signed up for loyalty programs and clubs at the POS using the POS snippets.

Tender Based Redemptions – bLoyal gift and loyalty tender can be seamlessly integrated into the POS using the bLoyal Payment Engine.

bLoyal Order Processing Certified:

Order Processing (POS Snippets) - Additionally, omni-channel order processing can be easily

added to any POS system by calling the order based POS snippets.

Table 1 below shows the integration components necessary to achieve each level of certification.

3.1 Key Concepts

These are some key concepts/resources relating to the Loyalty Engine and Loyalty Grid APIs. These

can also be referred to collectively as the bLoyal System APIs.

Client Login Domain – This is the login domain of the bLoyal account being targeted by the bLoyal API.

Connector Key – This is a key value that identifies the specific application (i.e. system) that is issuing bLoyal API requests.

API Key – This is a value used in the generation of an access key and is defined to be at either the Device, Store, or Client level.

Access Key – This is a key value that is generated from the combination of a connector key

and an API key. It is used in conjunction with the client login domain to authenticate access

to the bLoyal System APIs.

Session Key – This is a key value that is generated from an access key. It is used to authenticate access to the bLoyal POS snippets.

System – This is used to describe the source system that is being integrated with bLoyal. A system could represent a single database, or a collection of databases.

Loyalty Engine API Reference: http://loyaltyenginebeta.bloyal.com/Help Grid API Reference: http://gridbeta.bloyal.com/Help

IMPORTANT: When using the bLoyal API, providing a ‘null’ value or leaving a field out of the

request entirely will result in that field being omitted from any entity updates. By contrast,

providing an “empty” value for a field will erase whatever data might have been present in that

http://loyaltyenginebeta.bloyal.com/Help

http://gridbeta.bloyal.com/Help


field previously. Keeping this in mind will help ensure the desired results when using the Loyalty Engine and Grid APIs.

3.2 Obtaining bLoyal Service URLs

A critical requirement to the success of any integration with bLoyal is to retrieve the client-specific

service URLs from bLoyal. This will provide service endpoints for the bLoyal Loyalty Engine, Grid,

Payment Engine, and POS Snippets, among others. Retrieval of this information is achieved in one

of two ways, depending on the use of bLoyal web API or Nuget packages (described below):

Using the bLoyal web API, a GET request can be issued to the following endpoint:

https://domain.bloyal.com/api/v4/serviceurls/{LoginDomain}

Using the bLoyal Nuget packages, the GetServiceUrlsAsync() method is used.

Once this information is retrieved, it should be cached in memory for quick access, as the

integration components described in this document are directly dependent on the service URLs

retrieved. The process to obtain service URLs from bLoyal should be performed according to the

following:

1. At “startup” of the integrated system – Whenever the external system starts up, bLoyal service URLs should be retrieved and cached in memory.

2. Prior to the start of a bLoyal integration batch.

If at any point while calling a bLoyal service a “ServiceRedirect” error code is returned, this

indicates that the client-specific service URL for that target service has changed and that the

cached service URLs should be updated. It is recommended that one of the following happen:

Restart the POS system – Since bLoyal service URLs should be obtained automatically at

startup, restarting the POS system will trigger an automatic update and should resolve the “ServiceRedirect” error. This could be a simple warning message to the POS cashier.

Automatically refresh the service URLs “behind the scenes” – To avoid a system restart, the

service URLs could be refreshed automatically and simply allow the POS cashier to retry the

previous bLoyal functionality.

3.3 Generating an Access Key

To generate an access key, make a POST request to the following bLoyal Grid resource, supplying

the appropriate client login domain, connector key, and API key. The GridApiUrl is from section 3.2

above:

{GridApiUrl}/api/v4/KeyDispenser

IMPORTANT: Once an access key has been generated, it should be stored securely and not

exposed via any UI. This access key provides API access to the target bLoyal account and it is

important that this key remain confidential.

3.4 Identifying external entities

When integrating with bLoyal, a link is established and maintained between the POS system

entities and the corresponding bLoyal entities (e.g. a POS transaction can be linked to a bLoyal

cart). This link can be in one of three forms:


1. ExternalId – This is a globally unique identifier across the entire POS system for a given

bLoyal client. Use this value if the POS entity has a unique identifier that is guaranteed

never to be duplicated.

2. SourceExternalId – This is an identifier that is unique only within a given store.

3. Uid – This is bLoyal’s unique identifier for the entity. Use this value if the POS system

doesn’t provide a unique identifier for the entity.

The mechanism that is chosen to establish this link should be consistently supplied throughout the

integration.

Example: For in-flow discounting and customer signup, if ExternalId is chosen to be used as the

unique identification field for the POS transaction, then the appropriate ExternalId field will need to

be provided when calling the calculate cart command resource, as well as when launching any POS

snippets used for customer signup. Similarly, for backend data integration, the ExternalId value

used when calculating in-flow discounts should also be provided when submitting the sales

transaction.

3.5 Web API vs. bLoyal Nuget Packages

The Loyalty Engine and Loyalty Grid are exposed via a set of RESTful API resources, as well as

bLoyal Nuget packages that provide method wrappers for those RESTful API resources. Both of

which are available for use when integrating with bLoyal.

RESTful Web APIs: For integrations being implemented in non-.NET environments, the web APIs

can be called directly. These web APIs support standard HTTP request methods (GET, POST,

etc.).

bLoyal Nuget Packages: For integrations being implemented in .NET environments (or if this is

the preferred method of implementation), bLoyal offers Nuget packages for both the Loyalty

Engine and Grid. These packages provide asynchronous method wrappers for their respective

set of APIs. These Nuget packages can be found on the bLoyal public MyGet feeds.

https://www.myget.org/F/bloyal/api/v3/index.json (Visual Studio 2015+)

https://www.myget.org/F/bloyal/api/v2 (Visual Studio 2012+)

https://www.myget.org/F/bloyal/api/v3/index.json

https://www.myget.org/F/bloyal/api/v2


Integration

Component API

bLoyal Certification Levels

Backend Certified In-Flow Certified Order Processing Certified

Backend Data Integration

bLoyal Loyalty Grid

One-Way -> to bLoyal Sales Transactions

Customers Products

Optional

Other entities as desired

One-Way -> to bLoyal [Same as Backend Certified]

Two-way Synchronization Customers Products

Optional

Departments Categories

Discount Reason Codes


One-Way -> to bLoyal [Same as In-Flow Certified]

Two-way Synchronization

[Same as In-Flow Certified] …and…

Inventory Transactions Available Inventory

Optional

Club Membership


Promotions and

Awards

bLoyal Loyalty

Engine

POS Snippets

In-Flow Discounting

Calculate Cart Command Approve Cart Command

Commit Cart Command POS Snippets – Loyalty Optional

POS/ApplyCoupon POS/RecordVisit

[Same as In-Flow Certified]

Customer Signup POS Snippets POS Snippets - Loyalty

POS/QuickSignup POS/QuickEdit POS/FindCustomer POS/ViewCustomer

Optional POS/GiftCardBalance


Tender Based Redemptions

bLoyal Payment Engine

Redeem as Tender CardRedeem() CardRefund()


Order Processing POS Snippets POS Snippets – Orders POS/CreateOrder

Table 1 – POS Certification Levels


4. bLoyal Loyalty GridTM – Backend Data Integration

The bLoyal Loyalty Grid is a set of highly scalable integration API that synchronize key data

between bLoyal and 3rd party applications. The Grid takes care of most of the heavy lifting

required to synchronize data between systems including dynamic identification and duplicate

resolution using bLoyal’s patent pending Dynamic Resolution TechnologyTM and merge conflicts

and exceptions. The Grid is exposed through the following base URI, where the GridApiUrl is from section 3.2 above:

{GridApiUrl}/api/v4/

4.1 Protocol – “Start” and “Close” Integration Batch

Unlike the Loyalty Engine where requests are issued in-flow of the transaction, the Grid is

intended to be called as part of a background process within the POS system.

The protocol for synchronizing data using the Grid involves calling the integration batches

resource once to start an integration batch and retrieve synchronization settings, synchronizing

data, and then calling the active integration batches resource to complete the synchronization

process.

Your Application bLoyal Grid

Integration Batches Resource (Start)

Integration Batch Profile Response

Active Integration Batches Resource (Close)

Integration Batch Response

...Entity Synchronization...

Figure 1 – bLoyal Grid Protocol

The integration batches and active integration batches resources are described below:

Integration Batches Resource (Start) – An integration batch should be started once

when the data replication service is ready to begin syncing data. When starting an

integration batch, it is strongly recommended that the ConnectorVersion and

ConnectorMachineName be provided in the request, as this grants visibility within the

client’s Loyalty Director account.

This request will return an IntegrationBatchProfile entity containing the following

information:

1. BatchUid – This value is auto-generated by bLoyal to uniquely identify the integration batch.


2. EntitySyncProfiles - A list of entities that are configured for synchronization, the

direction with which they should be synchronized, and a priority assignment.

Entities should be synchronized in priority order. For example, all priority 1

entities should be synced before priority 2 entities. Within each priority, entities can be synced in any order.

3. ConnectorSettings - A list of connector-specific settings configured by the bLoyal

client in their Loyalty Director account (e.g. username and password used for

external communications).

4. CustomStateData - A list of custom state data that was provided when closing the previous integration batch.

Active Integration Batches Resource (Close) – The active integration batches

resource should be called once the data synchronization task has completed. This

informs bLoyal that the synchronization service for the POS is now idle.

This resource accepts the following data as input:

1. BatchUid – This is the BatchUid obtained when starting the integration batch.

2. BatchMessage – A unique message provided by the POS system that is associated to this integration batch.

3. CustomStateData – Any custom data that needs to be maintained between batches (e.g. entity revision # from the POS system).

This resource will return an IntegrationBatch entity containing the following information:

1. Title – A bLoyal-generated title for the integration batch.

2. Status – Open, Cancelled, or Closed.

3. Message – Echo of the BatchMessage from the request.

4. EntitySyncEvents – A summary of the entity synchronization that occurred, including number of imported entities and number of exported entities.

4.2 Synchronizing Entities

Data synchronization of the appropriate entities should occur after the call to the integration

batches resource (Start) and before the call to the active integration batches resource (Close).

The entities that are configured for synchronization are indicated in the IntegrationBatchProfile.

There are three Grid API requests that will need to be made to complete the synchronization of

a single entity. The order in which the synchronization calls are made is very important. The

POS system should first submit all pending changes that have occurred since the last data

synchronization task to bLoyal (import). Once those changes have been sent to bLoyal, the POS

system should then process any entity updates from bLoyal (export).

See the sequence diagram below.


Your Application bLoyal Grid

...Repeat above Get/Acknowledge sequence

for each entity specified

in the IntegrationBatchProfile until no more changes

are returned…

Save Changes <Entity> Resource

Get Changes <Entity> Resource

Entity Changes Response

Acknowledge Changes <Entity> Resource

Figure 2 – Entity Synchronization

Note: The <Entity> token in the name can be replaced by the name of the specific entity to be

synchronized (e.g. Customer, Product, SalesTransaction, etc.).

Save Changes <Entity> Resource – The POS system needs to have a mechanism to

detect and keep track of changes that occur to entities. This is normally done either by

setting a “HasChanged” flag on the entity or keeping a queue/table of ID’s for the

entities that have changed. The save changes resource should be called for each entity

that has changed since the last time data synchronization occurred.

The save changes resource supports a ChangeType field, for which the accepted values

are “Modified” or “Deleted”. When the intent is to create a new entity or update an

existing entity, a ChangeType of “Modified” should be supplied. When the intent is to

delete an existing entity, use “Deleted” as the ChangeType.

This request is optimized to accept bulk changes, so submitting sets of changes are

encouraged. For performance reasons, it is recommended that sets be limited to 500

changes at a time.

Get Changes <Entity> Resource – The get changes resource returns a list of entities

that have been added, updated, or deleted in bLoyal. A list of changes will be returned

and the number of changes varies depending on the entity type that is requested.

IMPORTANT: If an entity is received from bLoyal that has been changed in the local

system (since the last call to save changes), it is recommended that the POS system

reject the change and allow the bLoyal resolution and exception logic to handle the

conflict.

Similar to the save changes resource, the get changes resource also supports a

ChangeType field. A value of “Modified” will be returned when the change represents

either a new entity in bLoyal or an update to an existing entity. A value of “Deleted” is

used to indicate that the entity was deleted from bLoyal and that the same action should

be taken within the POS system.


After processing the changes locally, acknowledgement of those changes needs to be

provided to the Grid using the acknowledge changes resource. Once a set of changes

have been acknowledged, additional calls to the get changes resource should be made

(and those changes acknowledged) until no more changes are returned, indicating that

there are no more pending changes for that entity in bLoyal to be processed by the POS

system.

Acknowledge Changes <Entity> Resource – The acknowledge changes resource

informs the Grid of the changes that have been processed (or rejected) into the POS

system. If a change was rejected (based on the scenario above), an acknowledgement

status of “Failure” should be provided. Otherwise, an acknowledgement status of

“Success” indicates that the POS system successfully processed the change into the local

system.

4.3 Supported Entities

The bLoyal Loyalty Grid supports synchronizing the following entities between systems.

Entities used by the bLoyal Loyalty Engine:

Customer

Product – Core product data such as SKU, name, price, etc…

Department – A top level grouping of a product, normally used for categorization.

Category – A secondary level of grouping, normally below a department.

SalesTransaction – Sales Transactions include customer, product, and payment

information.

ReasonCode – Reason codes are used for discounting and tracking within bLoyal.

Additional entities used for various reasons:

AvailableInventory – The AvailableInventory entity represents the current inventory

available (calculation of on-hand minus committed) for a given product at a given store.

bLoyal tracks inventory, but is not the inventory management system so this number is a snapshot in time from your system.

InventoryTransaction – An inventory transaction is generated by bLoyal each time an

order is approved (committed inventory) or fulfilled (on-hand inventory). Inventory

transactions are associated to inventory locations (i.e. an inventory holding location) and can be submitted to bLoyal from an external system.

Catalog (CatalogSection) – bLoyal provides a flexible product catalog capability for

grouping products in an unrestricted hierarchy structure. bLoyal Clients often use this for the classification for their web store products, for example.

ProductBrand – bLoyal provides the ability to define brands that can be used for

product classification.

Supplier – bLoyal provides the ability to define suppliers that can be used for product classification.


5. bLoyal Loyalty EngineTM – Promotions and Awards

The Loyalty Engine enables the addition of real-time promotions and loyalty award redemptions

to the POS register as part of a transaction or ticket. The Loyalty Engine is exposed through the

following base URI, where the LoyaltyEngineApiUrl is from section 3.2 above:

{LoyaltyEngineApiUrl}/api/v4/

Customers can redeem their benefits as discounts on a transaction or as a tender. bLoyal

supports both methods and both are required for a bLoyal certified integration.

5.1 In-flow Promotions and Redemptions

There are two scenarios for adding the bLoyal Loyalty Engine in-flow of the transaction. The

first scenario involves using the customer database of the local POS system to find and set the

customer to the transaction and second scenario leverages bLoyal to find and set the

transaction customer. Each is shown below.

Scenario 1 – Use local POS system customer database to find/create the customer prior to

calling the Loyalty Engine.

In this scenario, the local application’s database is used as the primary customer database

and the bLoyal loyalty processing service is used to calculate benefits and accrue rewards.

The customer will be automatically created in bLoyal if the customer doesn’t already exist.

POS Transaction bLoyal Loyalty Engine

Calculate Cart Command

Calculated Cart Response

...Tender the sale at the POS...

Approve Cart Command

Cart Approval Response

Commit Cart Command

Cart Commitment Response

...Before going to tender screen at the POS...

Figure 3 – In-flow with customer set in the POS system

Step 1: Calculate Cart Command - The calculate cart command takes a cart as input

(and any coupons the cashier applied) and runs it through the bLoyal promotions and

loyalty engine to determine which, if any, discounts apply. As an alternative to designing


a coupon entry UI at the POS, the POS/ApplyCoupon POS Snippet (described in section

6) can be used to apply bLoyal coupons to the transaction.

A link between the POS transaction and the corresponding bLoyal cart used for Loyalty

Engine calculations is established by using any one of the fields previously mentioned in

the “Integration Overview” section: CartExternalId, CartSourceExternalId, or CartUid.

The POS system will need to supply one of these fields to establish and maintain this

link.

This resource will return a CalculatedCart response entity containing the following

information:

1. A modified cart with any discounts that were applied.

2. A summary of any loyalty points or currency that will accrue or be used when the

transaction is completed (if applicable).

3. A list of CartAlert entities.

Each CartAlert entity will contain a SnippetUrl. The POS system should launch any URLs

that are returned. The URL endpoint will provide the cashier with the mechanism to

either acknowledge or resolve the alert.

IMPORTANT: Additional calls to the calculate cart command should continue to be

made until the response returns zero CartAlerts.

The POS system should display any promotions that are returned, as well as show any

loyalty points that will accrue and/or be used on the transaction.

Note: If bLoyal Order Processing functionality is being used, please refer to section 8.2

below for details on how to apply bLoyal-calculated shipping charges and destination

based sales tax.

The calculate cart command should be called automatically prior to tendering a sale.

The POS system should also provide a way to manually initiate a calculate cart command

so that the cashier can check for promotions at any point during the transaction. A call

to the calculate cart command should be made on every transaction at the POS

regardless of the whether a customer is set to the transaction or not.

IMPORTANT: If any changes are made to the transaction after calling the calculate cart

command, another call to that command will be necessary to re-calculate applicable

promotions, making sure to provide the same transaction identifier used previously

(CartExternalId, CartSourceExternalId, or CartUid).

Step 2: Approve Cart Command – When the transaction is tendered, but before payment

is collected, the POS system should make a call to the approve cart command. This

resource is used to determine any errors that would prevent the transaction from being

successfully received by bLoyal. This is most commonly used for order processing

scenarios, but is required for any certified bLoyal integration.

This resource will return a CartApproval response entity containing the following

information:

1. A Boolean value indicating a successful (or failed) approval.


2. A list of CartAlert entities.

IMPORTANT: The approve cart command should only be called once the calculate cart

command has returned zero CartAlert entities (details above). Additional calls to the

approve cart command should continue to be made until the response returns zero

CartAlerts.

Step 3: Commit Cart Command – Once the transaction has been successfully tendered

and funds collected, the POS system should call the commit cart command. This

lightweight call will capture any loyalty benefits that were accrued/redeemed on the

transaction. It will also return the customer’s current loyalty summary and any receipt

messages (configured via bLoyal Loyalty Director) that are intended to be shown on the

receipt.

This resource will return a CartCommitment response entity containing the following

information:

1. Confirmation of the loyalty points and currency both accrued and redeemed on

the transaction.

2. A loyalty summary for the transaction’s customer, if applicable, containing loyalty points, currency, and frequent buyer balances.

IMPORTANT: The commit cart command should only be called once the approve cart

command has returned zero CartAlert entities (details above).

Scenario 2 – Use bLoyal customer database to find/create customers prior to calling the

Loyalty Engine.

In this scenario, the bLoyal customer database is used as the primary customer database.

This enables global customer viewing and editing across stores and sales channels. You can

either use the Loyalty Engine for finding and creating customers or launch a POS snippet (as

described in section 6).

Step 1: Launch the FindCustomer POS snippet to locate the desired customer in the bLoyal

system use QuickSignup POS snippet to quickly create a new customer.

The remaining steps are the same as Scenario 1.

5.2 Customer and Subscriber Group Signup (optional)

Capturing customer information and adding them to subscriber groups are key elements in

accruing loyalty benefits. A customer record must exist for a customer to accrue loyalty points

and currency. A subscriber group in bLoyal is an externally available membership list that a

customer can opt-in to. Subscriber groups are used to include customers in loyalty programs and mailing lists.

The easiest way to add customer signup capability to your POS application is using the POS

Snippets (described in section 6). However, if a custom UI is desired for capturing customer

data and subscriber group memberships, the same functionality can be achieved by using the

Loyalty Engine. The sequence diagram below shows the calls necessary for signing up customers.


Your Application bLoyal Loyalty Engine

Get Subscriber Groups Resource

Subscriber Group List Response

Signup Customer Command

Customer Response

Save Customer Command

Customer Response

Join Subscriber Group Command

Command Response

Leave Subscriber Group Command

Command Response

...OR...

...PLUS...

Get Customer Command

Customer Response

Figure 4 – Customer Signup with Subscriber Group

1. Get Subscriber Groups Resource – Returns a list of subscriber groups currently available for customer signup.

2. Save/Signup Customer Command – The save customer command is used to update

an existing customer, but does not have the ability to add/remove subscriber group

memberships for the customer. The signup customer command is used to create a new customer AND join them to the designated subscriber groups (Save + Join).

3. Join/Leave Subscriber Group Command – Create a new subscriber group

membership for an existing customer or remove an existing customer from a subscriber

group.

4. Get Customer Resource – Returns the core customer information.


6. POS Snippets – Customer Signup

POS Snippets are specialized bLoyal hosted web pages that provide targeted bLoyal

functionality to cashiers. The POS Snippets are intended to be an easy way to add additional

customer and order processing capability to your POS system.

All POS Snippets are launched in the same way by POSTing the query string parameters

mentioned below to the following base URL, where the POSSnippetsUrl is from section 3.2

above:

{POSSnippetsUrl}/POS

6.1 Launching a POS Snippet

POS Snippets interact with the Loyalty Engine using either your unique CartExternalId or

CartSourceExternalId, or the bLoyal generated CartUid.

Launching a POS Snippet is easy. Your POS system only needs to support a “Customer POS

Button” that can launch a browser in a framed window using a modal type dialog (meaning the

POS system should wait until the user is done with the window before doing anything else).

The sequence diagram below shows for how to launch a POS Snippet.

Your Application bLoyal POS Snippet

POS/

[SnippetName]?SessionKey=###&CartExternalId=###

&LoginDomain=###

...Normal POS processing...

Get Session Resource

Session Key

Calculate Cart Command

Calculated Cart Response

Figure 5 – Launching a POS Snippet

1. Get Session Resource – In order to launch a POS Snippet, a session key is required to

bind the snippet session to the bLoyal Device assigned to the POS Register. The get

session resource uses an API Access Key to create a session key. This should be called prior to launching any POS Snippet URL.


2. Launch the POS/[SnippetName] – When launching a snippet URL the following query string parameters are required.

SessionKey – This was obtained above.

CartExternalId, CartSourceExternalId, or CartUid – This is required to link

the snippet session to the appropriate bLoyal cart used for Loyalty Engine

promotion calculations.

LoginDomain – This is the login domain for the bLoyal account, which should be a configurable setting within the POS system.

CashierCode – This is the identifier of the current POS cashier or user. This is used by bLoyal to enforce certain cashier vs. manager override configurations.

6.2 Supported POS Snippets

bLoyal provides several POS Snippets. They are all used in conjunction with the Loyalty Engine

as a mechanism to exchange transaction data between the POS system and bLoyal. POS

Snippets are configured by the bLoyal client based on their unique requirements.

Below is the list of POS Snippets provided for customer signup. Ideally, the POS application can support launching a POS snippet by adding a custom POS button to the register.

bLoyal In-Flow Certified integrations can use the following POS Snippets:

POS/QuickSignup – Provides a simple way for a cashier to create a new bLoyal customer.

POS/QuickEdit – Provides a simple way for a cashier to edit information for an existing

bLoyal customer.

POS/FindCustomer – Presents the cashier with the bLoyal find customer screen where the cashier can easily find the customer or scan a loyalty card.

POS/ApplyCoupon – Provides the ability for the cashier to scan in a coupon or lookup

the awarded coupons for a customer and apply the coupon to the transaction. (Promotions and Awards)

POS/RecordVisit – Records a visit for a customer. If no customer has been set to the

transaction then it provides UI to scan or enter customer information. (Promotions and Awards)

POS/ViewCustomer – Provides a full view of the customer to enable the cashier to

better serve the customer. Includes current loyalty balances, purchase history, program and club signup, pickup orders, etc.

POS/GiftCardBalance – Checks the balance of a bLoyal Gift Card or eGift Card.


7. bLoyal Payment EngineTM - Tender Based Redemptions

Promotions and awards can be redeemed by the Payment Engine as a payment tender using

the following tender types: Gift and eGift Cards or Loyalty Currency. Integrating bLoyal as a

payment tender into an application is similar to integrating with any other gift card processor.

The Payment Engine is exposed as a service using the following URL, where the PaymentApiUrl

is from section 3.2 above:

{PaymentApiUrl}/ws35/PaymentEngine.svc

There is a single set of API methods to use, regardless of the type of tender. By providing a

TenderCode and CardNumber (or Customer Uid), the Payment Engine is capable of determining

the type of tender - Gift Card, eGift Card, or Loyalty Currency – and performing the necessary

action.

The complete list of card processing calls is below.

GetCardBalance() – Returns the current and available balance of the Gift card, eGift card or Loyalty card.

CardAuthorize() – Authorizes a charge to the card and puts a hold on the card.

CardRelease() – Releases a previous authorization/hold that was put on a card.

CardCapture() – Captures a previous authorization.

CardRedeem() – Redeems a value from a card (the same as Auth + Capture).

CardRefund() – Refunds an amount to a card based on a previous capture or redeem transaction.

CardCredit() – Loads a card with a balance. This is used when a customer activates a

gift card or loads an amount to a card.

CardDebit() – Take an amount off of a card.

The sequence diagrams below show how to redeem as a payment tender and load a balance

onto a card.

Your Application bLoyal Payment Engine

GetCardBalance

Card Response

CardAuthorize

Card Response

CardCapture

Card Response


Figure 6 – Gift and Loyalty Processing as a Payment Tender

Your Application bLoyal Payment Engine

CardCredit

Card Response

Figure 7 – Loading a balance on a gift or loyalty card


8. bLoyal Order Processing

Additional functionality is provided to enable bLoyal omni-channel order processing at the POS.

A bLoyal Order Processing Certified integration will make use the following functionality:

CreateOrder POS Snippet

bLoyal-calculated shipping charges and destination based sales taxes

Product Inventory replication

8.1 POS Snippets

bLoyal provides the following POS Snippet(s) that allow omni-channel order processing

capabilities to be integrated into the POS system.

POS/CreateOrder – Creates either a shipping order or pickup order from the current

POS transaction. One of the supported transaction identifiers (CartExternalId,

CartSourceExternalId, or CartUid) will need to be supplied when launching the

CreateOrder snippet. Prior to launching this snippet, a call must be made to the

Loyalty Engine’s calculate cart command. This is how the products on the transaction are

made available to the CreateOrder snippet. Once the snippet closes, another call to

the calculate cart command resource will need to be made. This will return shipping

charges and destination based sales taxes, which should be applied to the POS transaction.

8.2 Shipping Charge and Sales Tax

Once a bLoyal order has been created using the CreateOrder POS snippet, the bLoyal loyalty

engine will return any applicable shipping charge(s) and sales tax(es). These will be included as

part of the CalculatedCart response entity, returned from the Calculate Cart Command. Based

on the configuration of the bLoyal account, the shipping charge and sales tax information will

be returned in one of the following formats:

1. Line Items – Shipping charge and sales tax will be returned as additional line items in

the CalculatedCart response entity. These additional line items should be applied directly

to the POS transaction as non-taxable line items. This option doesn’t require any special

handling because it only requires adding additional line items to the transaction.

2. Accounts – Shipping charge and sales tax will be returned in the Accounts object of the

CalculatedCart response entity. This option is intended to meet the needs of a POS system that leverages accounts for applying non-taxable charges to a transaction.

3. Native – Shipping charge and sales tax will be returned in the CartShipment object of

the CalculatedCart response entity. This option is intended to meet the needs of a POS

system that already contains a concept of shipments, as it will be easy to map the

bLoyal API response to the native POS transaction structure.

IMPORTANT: Line items marked with the “DoNotTax” flag in the CalculatedCart response

entity should be marked as “non-taxable” in the POS system.

bLoyal will return destination-based sales taxes for any items included in a shipping-type

shipment (as configured in the CreateOrder POS snippet). When this happens, it is important

that the POS system no longer calculate taxes for those items, since bLoyal has assumed this

responsibility by nature of the order processing functionality. To notify the POS system of which

items on the transaction should be marked as “non-taxable” by the POS system, the


appropriate line items in the CalculatedCart response entity will be set with a “DoNotTax” flag.

If this flag is set to “true”, the corresponding line item on the POS transaction should be

marked as non-taxable. If this flag is set to “false”, the POS system should apply its own local

taxes to that item normally.

8.3 Inventory Replication

A bLoyal Order Processing Certified integration should replicate product inventory between

bLoyal and the POS system using the backend integration component. Please refer to section 4

above for more information on the design of a backend integration.

The following Grid API entities can be used to perform inventory replication:

AvailableInventory – The AvailableInventory entity represents the current inventory

available (calculation of on-hand minus committed) for a given product at a given store.

bLoyal tracks inventory, but is not the inventory management system so this number is a snapshot in time from your system.

InventoryTransaction – An inventory transaction is generated by bLoyal each time an

order is approved (committed inventory) or fulfilled (on-hand inventory). Inventory

transactions are associated to inventory locations (i.e. an inventory holding location) and

can be submitted to bLoyal from an external system.

Example: An integration might use the InventoryTransaction entity to retrieve product

inventory transactions from bLoyal and process those into the external system, updating the

local product inventory as necessary. These inventory transactions would include adjustments

made as a result of web store orders or other integrated systems. The integration would then

submit inventory transactions back to bLoyal using an “ExternalReset” type so as to reset

bLoyal’s product inventory to include any inventory adjustments that would’ve resulted from

sales in the POS system. Once completed, these two actions will ensure that both the POS

system and bLoyal have matching product inventory.


9. bLoyal Logging (optional)

bLoyal provides the optional ability to accept error, warning, and informational logs from the

POS system for tracking and troubleshooting purposes. This is not a required component of

bLoyal POS integrations, but provides flexibility to those systems that don’t do their own

logging.

Depending on the mechanism by which the POS system is connecting to the bLoyal System

APIs, the procedure for utilizing bLoyal’s logging capabilities differs. If the integration is making

use of the bLoyal Nuget packages (described in section 3.5 above), logging capabilities are

inherited via the bLoyal package(s). If the integration is making direct calls to the web API

resources, the POS system will be responsible for capturing logs locally before submitting them

to bLoyal.

LogEvent entities are submitted to bLoyal and can represent one of several “events”, including

but not limited to: Info, Warning, or Error.

9.1 Protocol – bLoyal Nuget packages

The ability to submit logs to bLoyal is included in both bLoyal Nuget packages. The Nuget

packages record log events to memory on the local machine and then using a single method,

submits those logs to bLoyal.

The following list contains the available methods that can be used to submit logs:

LogInfo() – This method is used to record an informational event.

LogWarning() – This method is used to record a warning event.

LogError() – This method is used to record an error event.

SubmitLogsAsync() – This method is used to submit all recorded logs to bLoyal.

LogInfo(), LogWarning(), and LogError() should all be called in-flow of the transaction, at the

time the particular event occurs. These methods will record the log event into memory on the

local machine. The purpose of this process is to optimize performance during the transaction

flow for the customer.

At a point in time that is “out of flow” of the transaction, the POS system should call

SubmitLogsAsync() to submit any recorded logs (i.e. in memory) to bLoyal. Depending on the

number of logs that have been recorded into memory, this may take some time to complete.

For this reason, it is highly recommended that this be done out of flow of the transaction. The

bLoyal Logger service will keep a maximum of 100,000 logs in memory, at which time it will

start ignoring any new logs that are recorded into memory.

The sequence diagram below shows how to record and submit logs to bLoyal.


Your Application bLoyal Logger

LogInfo()

SubmitLogsAsync()

LogWarning()

LogError()

Figure 8 – bLoyal logging using Nuget packages

9.2 Protocol – RESTful Web APIs

When calling the bLoyal web APIs directly, the POS system is responsible for capturing logs

locally and then submitting them to bLoyal at a later time via a back-end process. The following

resources are provided in the bLoyal System APIs for submitting logs:

Logger Resource – This resource provides the ability to submit a single log event to bLoyal.

Logger (Multiple) Resource – This resource provides the ability to submit multiple log

events to bLoyal at one time.

The back-end process being run by the POS system should read from the local logs and submit

those to bLoyal using one of the above resources.


10. Appendix A: bLoyal API Mappings

Appendix A contains a mapping of user-friendly resource names to API resources.

Integration Batches Resource - POST api/v4/{accessKey}/IntegrationBatches

Active Integration Batches Resource - POST api/v4/{accessKey}/IntegrationBatches/Active

Calculate Cart Command - POST api/v4/{accessKey}/carts/commands/calculates

Approve Cart Command - POST api/v4/{accessKey}/carts/commands/approve

Commit Cart Command - POST api/v4/{accessKey}/carts/commands/commit

Record Visit Resource - POST api/v4/{accessKey}/visits

Get Subscriber Groups Resource - GET api/v4/{accessKey}/subscribergroups

Save Customer Command - POST api/v4/{accessKey}/customers/commands/saves

Signup Customer Command- POST api/v4/{accessKey}/customers/commands/signups

Join Subscriber Group Command - POST api/v4/{accessKey}/subscribergroups/commands/joins

Leave Subscriber Group Command - POST api/v4/{accessKey}/subscribergroups/commands/leaves

Get Customer Resource - GET api/v4/{accessKey}/customers/{uid}

Get Session Resource - GET api/v4/{accessKey}/session

Save Changes <Entity> Resource - POST api/v4/{accessKey}/{Entity}/Changes

Get Changes <Entity> Resource - GET api/v4/{accessKey}/{Entity}/Changes

Acknowledge Changes <Entity> Resource - POST api/v4/{accessKey}/{Entity}/Changes/Acks

Logger Resource – POST api/v4/{accessKey}/Logger

Logger (Multiple) Resource – POST api/v4/{accessKey}/Logger/Multiple

http://gridbeta.bloyal.com/Help/Api/POST-api-v4-accessKey-IntegrationBatches

http://gridbeta.bloyal.com/Help/Api/POST-api-v4-accessKey-IntegrationBatches-Active

http://gridbeta.bloyal.com/Help/Api/POST-api-v4-accessKey-IntegrationBatches-Active

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-carts-commands-calculates

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-carts-commands-approve

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-carts-commands-commit

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-visits

http://loyaltyenginebeta.bloyal.com/Help/Api/GET-api-v4-accessKey-subscribergroups-uid

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-customers-commands-saves

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-customers-commands-signups

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-subscribergroups-commands-joins

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-subscribergroups-commands-joins

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-subscribergroups-commands-leaves

http://loyaltyenginebeta.bloyal.com/Help/Api/POST-api-v4-accessKey-subscribergroups-commands-leaves

http://loyaltyenginebeta.bloyal.com/Help/Api/GET-api-v4-accessKey-customers-uid

http://loyaltyenginebeta.bloyal.com/Help/Api/GET-api-v4-accessKey-session

http://gridbeta.bloyal.com/Help/Api/POST-api-v4-accessKey-Customers-Changes

http://gridbeta.bloyal.com/Help/Api/GET-api-v4-accessKey-Customers-Changes

http://gridbeta.bloyal.com/Help/Api/POST-api-v4-accessKey-Customers-Changes-Acks

http://gridbeta.bloyal.com/Help/Api/POST-api-v4-accessKey-Customers-Changes-Acks

http://gridbeta.bloyal.com/Help/Api/POST-api-v4-accessKey-Logger

http://gridbeta.bloyal.com/Help/Api/POST-api-v4-accessKey-Logger-Multiple


11. Revision History

Date Rev Person Description

1/18/2016 1.0 Michael Hermes Created for v4 Loyalty Engine, Grid, and Payment

Engine APIs.

2/2/2016 1.1 Michael Hermes Updated the document to include the optional

bLoyal logging resources.

2/15/2016 1.2 Michael Hermes Grammatical updates and clarification.

8/15/2016 1.3 Michael Hermes Update to include BatchUid as output from the

Integration Batches and input to the Active

Integration Batches resources.

9/15/2016 1.4 Michael Hermes Update to include GetServiceUrls information and

CashierCode for POS snippets.

10/24/2016 1.5 Michael Hermes Several cleanups to POS snippet references.

11/2/2016 1.6 Michael Hermes Added ConnectorVersion and

ConnectorMachineName to StartIntegrationBatch

section.

12/1/2016 1.7 Michael Hermes Added more detail to the “Order Processing”

section. Updated names of Grid API entities to be

singular.

Documents

bLoyal POS Integration Guide - Customer Loyalty Software ......Order Processing (POS Snippets) - Additionally, omni-channel order processing can be easily added to any POS system by