Integrating POS Systems
Getting Started
This document provides step by step instructions on how to integrate a POS system with CRM.COM Rewards platform, using a set of Web API methods provided by CRM.COM and following either one or both of the two models described below:
- Front-End Reduction Model: In this model the customer is identified through CRM.COM, the itemised POS sales transaction is submitted to CRM.COM in order to be awarded and redemption is done real time, either automatically or per customer request, resulting to a reduction on the POS for the amount to pay
- Back-End Reduction Model: In this model the customer is identified through CRM.COM, the itemised POS sales transaction is submitted to CRM.COM in order to be awarded but redemption is done always automatically at the back-end through a payment gateway such as PayPal. In this model, no reduction is applied on the POS sales transaction
Best Practices
Authentication
Before performing any logical unit of work, an authentication token must be acquired. Acquiring an authentication token can be accomplished by using one of the two methods
- Web API Keys
- Username & Password
Visit API Authentication for more information. Also, check the Best Practices section below to find out some tips that will help you while Integrating with a POS System
Using Fields Set
CRM.COM Web API offers the possibility to select the fields to be retrieved from each API method by specifying the fields_set input parameter. This parameter provides the possibility to filter the results and retrieve only the fields that are provided on the method (separated by a comma). If nothing is specified in fields_set then all the fields will be retrieved
Visit Using Fields Sets for more information and examples
Using Pagination
There are API methods which retrieve a large number of entities such as list API methods. Some of these CRM.COM API methods provide the option to apply pagination on the results retrieved
Visit Using Pagination for more information and examples
Integration Scenarios
Purchase and Spend Award Flow
The flow described bellow is a simple example of integrating both purchase and spend awards into a system
Step 1 - Customer identification
- The customer is identified on the POS system by specifying his/her identifier (email address, card number, phone number, mobile app code etc.) using the POST rewards_participants/show method
- There are three ways to identify a customer (referred as rewards participant in CRM.COM)
- id: The rewards participant's id is provided
- number: The rewards participant's number is provided
- access_token_identifier: Rewards participant's access token is the most common parameter to use in order for the customer to be identified. Access tokens can be assigned to rewards participants in order to uniquely identify them and usually are mapped to the customer's email address, phone number or card number. Check Additional Documentation section below to find more information related to Access Tokens
- Once the customer is identified then the following customer information, which is returned by the Web API, is displayed on the POS
- accounts_receivable.account_owner.name: The name of the customer
wallet.balance: The wallet balance of the customer
Customer identification Web API example
https://hostname/crmapi/rest/v2/rewards_participants/show
Example of POS System after the customer identification
Customer is being identified providing his/her identifier (email address, card number, phone number, mobile app code etc.)
Once the customer is identified then the customer name and available wallet balance are displayed on the POS
Step 2 - Submitting the sales transaction
Once the customer pays then the sales transaction is submitted in CRM.COM as a purchase customer event through the POST customer_events/purchases/create API, by capturing the following information:
- The related customer (accounts_receivable_identifier)
- The sales transaction's reference number (reference_number)
- The sales transaction's date (performed_on)
- The sales transaction's merchant (performed_by_unit_identifier)
- The sales transaction's total amount (total_amount)
- The sales transaction's items and the amount per each item (products_set)
Note that the products should already exist in CRM.COM in order for the POS to make transactions for them. Visit Managing Products for more information on how to create and update them - Optionally the identifier of the POS can be specified (external_system)
Submit Purchase Web API example
https://hostname/crmapi/rest/v2/customer_events/purchases/create
Step 3 - Spend Request
Customer may want to spend some of the available wallet amount on that transaction. The reduction is submitted in CRM.COM as a spend request customer event capturing the following information using the POST customer_events/spend_requests/create method
- The related purchase customer event that was created above (purchase_customer_request_identifier)
The amount that is requested to be spend (spend_amount)
This call will return back the actual amount that was spent, which might be different than the amount that was requested to be spend (spend_reward_transaction.total_amount). This amount will be used in the next step to reduce the sales transaction total amount
Submit Spend Request Web API example
https://hostname/crmapi/rest/v2/customer_events/spend_requests/create
Example of POS System spend request form
- The following information is displayed
- The amount that can be requested to be spent on that transaction (wallet.balance)
Step 4 - Reducing & closing the sales transaction
- Once the sales transaction (purchase customer event) and spend transaction (spend request customer event) are submitted successfully and only if the reduction method is set to "Front-End Reduction" then the redemption amount is calculated as follows
The actual amount that was spent. The actual amount is mapped to the "total_amount" of the "spend_reward_transaction" after submitting the POST customer_events/spend_request/create method above and it may varies from the requested spend amount (additional spending conditions may apply)
- The amount that was spent automatically, which is the total_spend_amount as retrieved by the POST customer_events/purchases/create used above. The total_spend_amount is the sum of total_instant_spend_amount, total_automatic_spend_amount and total_additional_spend_amount (all these three values are retrieved from the same method)
- The calculated redemption amount is deducted from the POS sales transaction by applying a discount on the sales transaction or adding a special product item or a specific tender type
- Upon completion, the following information is displayed and printed on the customer's receipt
- The amount that was awarded for that purchase, which is the total_awarded_amount retrieved by the POST customer_events/purchases/create used above
- The wallet balance after the purchase. This is calculated as the "wallet's initial balance + awarded amount - redemption amount"
Example of POS System after submitting a spend request
Example of POS System Receipt
Purchase and Spend Award Advanced Flow
The flow described bellow is another example (with additional steps) of integrating both purchase and spend awards into a system
Step 1 - Customer identification
- The customer is identified on the POS system by specifying his/her identifier (email address, card number, phone number, mobile app code etc.) using the POST rewards_participants/show method
- There are three ways to identify a customer (referred as rewards participant in CRM.COM):
- id: The rewards participant's id is provided
- number: The rewards participant's number is provided
- access_token_identifier: Rewards participant's access token is the most common parameter to use in order for the customer to be identified. Access tokens can be assigned to rewards participants in order to uniquely identify them and usually are mapped to the customer's email address, phone number or card number. Check Additional Documentation section below to find more information related to Access Tokens
- Once the customer is identified then the following customer information, which is returned by the Web API, is displayed on the POS
- accounts_receivable.account_owner.name: The name of the customer
wallet.balance: The wallet balance of the customer
Customer identification Web API example
https://hostname/crmapi/rest/v2/rewards_participants/show
Example of POS System after the customer identification
Customer is being identified providing his/her identifier (email address, card number, phone number, mobile app code etc.)
Once the customer is identified then the customer name and available wallet balance are displayed on the POS
Step 2 - Previewing rewards information
- Before completing the sales transaction on POS, the itemized POS transaction is passed as parameter to the POST customer_events/purchases/preview method in order to preview the amount that will be awarded, the amount that will be spend instantly and the additional amount that can be spent on a sales transaction (purchase customer event), prior to submitting the transaction
- The preview function will also determine if the purchase customer event that will be submitted can be redeemed by the Front-End System (i.e. the POS) or by a Back-End System. Additionally, information retrieved by this method will be afterwards used by subsequent steps of this flow
Preview Web API example
https://hostname/crmapi/rest/v2/customer_events/purchases/preview
Example of POS System while previewing the sales summary
The following information is displayed
The reduction Method (reduction_method)
The amount to be awarded (total_award_amount)
- The amount that will be spend automatically, without the customer's request (the sum of total_instant_spend_amount and total_automatic_spend_amount)
- The amount that is available to be spend on that transaction (total_additional_spend_amount)
- The redemption amount, which is the amount that will be deducted from the transaction, which at this point is equal to the amount that will be spend automatically
Step 3 - Submitting the sales transaction
Once the customer pays then the sales transaction is submitted in CRM.COM as a purchase customer event through the POST customer_events/purchases/create API, by capturing the following information:
- The related customer (accounts_receivable_identifier)
- The sales transaction's reference number (reference_number)
- The sales transaction's date (performed_on)
- The sales transaction's merchant (performed_by_unit_identifier)
- The sales transaction's total amount (total_amount)
- The sales transaction's items and the amount per each item (products_set)
Note that the products should already exist in CRM.COM in order for the POS to make transactions for them. Visit Managing Products for more information on how to create and update them - Optionally the identifier of the POS can be specified (external_system)
Submit Purchase Web API example
https://hostname/crmapi/rest/v2/customer_events/purchases/create
Step 4 - Spend Request
If "Front-End Reduction" is allowed then the customer may want to spend some of the available wallet amount on that transaction. Using the results of the POST customer_events/purchases/preview method used above, the following information should be available on POS once the agent selects the Spend Amount option.
- Total additional spend amount, which is the amount that can be requested to be spent on that transaction (total_additional_spend_amount)
- The minimum spend amount allowed to be spend per transaction (minimum_spend_amount_per_transaction)
- The maximum spend amount allowed to be spend per transaction (maximum_spend_amount_per_transaction)
If either "Front-End Reduction" or "Back-End Reduction" is allowed, then the reduction is submitted in CRM.COM as a spend request customer event capturing the following information using the POST customer_events/spend_requests/create method
- The related purchase customer event that was created above (purchase_customer_request_identifier)
The amount that is requested to be spend (spend_amount)
This call will return back the actual amount that was spent, which might be different than the amount that was requested to be spend (spend_reward_transaction.total_amount). This amount will be used in the next step to reduce the sales transaction total amount
Submit Spend Request Web API example
https://hostname/crmapi/rest/v2/customer_events/spend_requests/create
Example of POS System spend request form
- The following information is displayed
- The amount that can be requested to be spent on that transaction (total_additional_spend_amount)
- The minimum spend amount allowed to be spend per transaction (minimum_spend_amount_per_transaction)
- The maximum spend amount allowed to be spend per transaction (maximum_spend_amount_per_transaction)
Step 5 - Reducing & closing the sales transaction
- Once the sales transaction (purchase customer event) and spend transaction (spend request customer event) are submitted successfully and only if the reduction method is set to "Front-End Reduction" then the redemption amount is calculated as follows
The actual amount that was spent. The actual amount is mapped to the "total_amount" of the "spend_reward_transaction" after submitting the POST customer_events/spend_request/create method above
- The amount that was spent automatically which is the sum of total_instant_spend_amount and total_automatic_spend_amount as retrieved by the POST customer_events/purchases/preview used above
- The calculated redemption amount is deducted from the POS sales transaction by applying a discount on the sales transaction or adding a special product item or a specific tender type
- Upon completion, the following information is displayed and printed on the customer's receipt
- The amount that was awarded for that purchase, which is the total_award_amount retrieved by the POST customer_events/purchases/preview used above
- The wallet balance after the purchase. This is calculated as the "wallet's initial balance + the awarded amount - redemption amount"
Example of POS System after submitting a spend request
Example of POS System Receipt
Purchase Award Flow
The flow described below is an example of integrating purchase award into a system. In this model, no reduction is applied on the POS sales transaction
Step 1 - Customer identification
- The customer is identified on the POS system by specifying his / her identifier (email address, card number, phone number, mobile app code etc.) using the POST rewards_participants/show method
- There are three ways to identify a customer (referred as rewards participant in CRM.COM):
- id: The rewards participant's id is provided
- number: The rewards participant's number is provided
- access_token_identifier: Rewards participant's access token is the most common parameter to use in order for the customer to be identified. Access tokens can be assigned to rewards participants in order to uniquely identify them and usually are mapped to the customer's email address, phone number or card number. Check Additional Documentation section below to find more information related to Access Tokens
- Once the customer is identified then the following customer information, which is returned by the Web API, is displayed on the POS:
- accounts_receivable.account_owner.name: The name of the customer
wallet.balance: The wallet balance of the customer
Customer identification Web API example
https://hostname/crmapi/rest/v2/rewards_participants/show
Example of POS System after the customer identification
Customer is being identified providing his/her identifier (email address, card number, phone number, mobile app code etc.)
Once the customer is identified then the customer name and available wallet balance are displayed on the POS
Step 2 - Submitting the sales transaction
Once the customer pays then the sales transaction is submitted in CRM.COM as a purchase customer event through the POST customer_events/purchases/create API, by capturing the following information:
- The related customer (accounts_receivable_identifier)
- The sales transaction's reference number (reference_number)
- The sales transaction's date (performed_on)
- The sales transaction's merchant (performed_by_unit_identifier)
- The sales transaction's total amount (total_amount)
- The sales transaction's items and the amount per item (products_set). Note that the products should already exist in CRM.COM in order for the POS to make transactions for them. Visit Managing Products for more information on how to create and update them.
- Optionally the identifier of the POS can be specified (external_system)
Submit Purchase Web API example
https://hostname/crmapi/rest/v2/customer_events/purchases/create
Step 3 - Reducing & closing the sales transaction
- Once the sales transaction (purchase customer event) is submitted successfully and only if the reduction method is set to "Back-End Reduction" then CRM.COM will automatically apply the following:
- Award the purchase customer event with any applicable awards
- Reduce the wallet balance by the amount of money that can be automatically spend by the customer on that purchase
- Refund that money through a payment gateway such as Paypal
- Send an email and/or SMS to the customer informing him / her about the awards and refunds that were applied
- No information should be printed on the customer's receipt since CRM.COM will automatically inform the customer for any awards or refunds that were applied
Sales Transaction Cancellation Flow
The flow described below is the flow that should be applied in order to cancel the sales transaction created. Upon cancellation, the Customer Events that may have been created (Purchase Customer Events and Spend Request Customer Events ) are also canceled
Step 1 - Cancelling the Purchase Customer Event
- The Sales Transaction is canceled through the POS System
The related to the sales transaction, Purchase Customer Event is also canceled through the Web API POST customer_events/purchases/cancel. If the purchase customer event that is about to be canceled is related with any spend request customer events, award reward transactions or spend reward transactions, then those transactions are canceled as well
Purchase Customer Event Cancellation Web API example
https://hostname/crmapi/rest/v2/customer_events/purchases/cancel
Additional Documentation
Visit CRM.COM Manuals in order to find more information related to the areas / concepts mentioned in above scenarios
Module | Description | Manuals' Link |
---|---|---|
Rewards Participant | Manage the customers who have signed up for Rewards or have been automatically selected to participate | Managing Rewards Participants |
Rewards Participating Merchants | Rewards Participating Merchants are merchants that have a partnership with the business that owns the Rewards platform and can participate in the provided Reward Schemes The Reduction Method that will be used to process the sales it is defined through the Participating Merchant | Managing Rewards Participating Merchants |
Rewards Offers | Reward Offers are used to
| Managing Rewards Offers |
Purchase Customer Events | Events linked with the purchase of goods | Purchase Customer Event |
Spend Request Customer Events | Events linked with the spending of Award points of Participants | Spend Request Customer Event |
Access Tokens | Access Tokens are used to identify and authenticate customers | Managing Access Tokens |
Products | Products are goods that used by business transactions in the System | Managing Products |