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

  1. 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
  2. There are three ways to identify a customer (referred as rewards participant in CRM.COM)
    1. id: The rewards participant's id is provided
    2. number: The rewards participant's number is provided
    3. 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
  3. Once the customer is identified then the following customer information, which is returned by the Web API, is displayed on the POS
    1. accounts_receivable.account_owner.name: The name of the customer
    2. wallet.balance: The wallet balance of the customer

 

Customer identification Web API example

POST Request
https://hostname/crmapi/rest/v2/rewards_participants/show
Body
{
  "token": "{{token}}",
  "rewards_participant_identifier":{"access_token_identifier":{"authentication_code":"test@crm.com"}},
  "fields_set":"accounts_receivable,wallet"
}
Response
{
    "status":
    {
        "message": null,
        "description": null,
        "code": "OK"
    },
    "data":
    {
      "wallet": {
      "number": "W0000000001",
      "balance": "5.00",
      "currency": {
        "suffix_symbol": "N/A",
        "prefix_symbol": "€",
        "decimal_part_name": "cents",
        "code": "EUR",
        "integer_part_name": "euro",
        "id": "2"
      },       
        "accounts_receivable":
        {
            "account_owner":
            {
                "last_name": "Last Name",
                "life_cycle_state": "FINANCIAL",                 
                "title": "Ms",
                "type": "PERSON",
                "first_name": "First Name",
                "name": "First Name Last Name",
                "id": "123456789",
                "demographics":
                {
                    "gender": "MALE",
                    "passport_number": "123456",
                    "social_security_number": "123456",
                    "date_of_birth":
                    {
                        "month": 1,
                        "day": 1,
                        "year": 1990
                    },
                    "name_day":
                    {
                        "month": 5,
                        "day": 5
                    },
                    "id_number": "123456"
                }
            },
            "life_cycle_state": "ACTIVE",
            "number": "400",
            "name": "First Name Last Name",
            "id": "123456789"
        }       
    }
}

 

Example of POS System after the customer identification

  1. Customer is being identified providing his/her identifier (email address, card number, phone number, mobile app code etc.)

  2. 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:

  1. The related customer (accounts_receivable_identifier)
  2. The sales transaction's reference number (reference_number)
  3. The sales transaction's date (performed_on)
  4. The sales transaction's merchant (performed_by_unit_identifier)
  5. The sales transaction's total amount (total_amount)
  6. 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
  7. Optionally the identifier of the POS can be specified (external_system)

 

Submit Purchase  Web API example

POST Request
 https://hostname/crmapi/rest/v2/customer_events/purchases/create
Body
{
   "token":"{{token}}",
   "accounts_receivable_identifier":{"number":"001"},
   "classification_identifier":{"name":"Purchase"},
   "performed_by_unit_identifier":{"name":"Unit"},
   "performed_on":"2017-05-22T16:05:00",
   "description":"Create Purchase event",
   "reference_number":"RF0000762",
   "total_amount":20,
   "net_amount":16,
   "vat_amount":4,
   "invoice_identifier":{"number":"I00003203"},
   "payment_medium_brand_identifier":{"name":"VISA"},
   "payment_medium_type_identifier":{"alternative_code":"CC"},
   "payment_medium_identifier":"PI000001",   
   "external_system":"POS",
   "fields_set":"number,id,reference_number,total_amount"
   "products_set":
   [
     {
       "product_identifier":{"code":"Soft Drinks"},
       "quantity":1,
       "total_amount":10,
       "net_amount":8,
       "vat_amount":2
     },
     {
       "product_identifier":{"code":"Sandwiches"},
	   "quantity":2,	 
       "total_amount":10,
       "net_amount":8,
       "vat_amount":2
     }
   ]
 }
Response
{
  "data": {
    "number": "111",
    "total_amount": 20,
    "id": "123456",    
    "reference_number": "RF0000762",
  },
  "status": {
    "code": "OK",
    "description": "",
    "message": ""
  }
}

Step 3 - Spend Request

  1. 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

    1. The related purchase customer event that was created above (purchase_customer_request_identifier)
    2. The amount that is requested to be spend (spend_amount)

  2. 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

POST Request
 https://hostname/crmapi/rest/v2/customer_events/spend_requests/create 
Body
{
   "token":"{{token}}",
   "accounts_receivable_identifier":{"number":"001"},
   "classification_identifier":{"name":"Spend Request"},
   "performed_by_unit_identifier":{"name":"Unit"},
   "purchase_customer_request_identifier":{"number":"936"},
   "performed_on":"2017-05-12T11:41:00",
   "description":"Spend Request",
   "spend_amount":10,
   "external_system":"POS",
   "fields_set":"spend_amount,type,number,id,life_cycle_state,performed_on,performed_by_unit,external_system,spend_reward_transaction"
 } 
Response
{
  "data": {
    "number": "294",
    "spend_amount": 10,
    "id": "12345678",
    "life_cycle_state": "POSTED",
    "type": "SPEND_REQUEST",
    "performed_on": "2017-05-12T11:41:00",
    "performed_by_unit": {
      "alternative_code": "U",
      "name": "Unit",
      "description": Unit,
      "id": "12345678"
    },
    "external_system": "POS",
    "spend_reward_transaction": {
      "number": "01",
      "vat_amount": 0,
      "total_amount": 10,
      "id": "12345678",
      "net_amount": 10,
      "life_cycle_state": "POSTED",
      "rewards_participant": {
        "number": "001",
        "accounts_receivable":
        {
            "account_owner":
            {
                "last_name": "Last Name",
                "life_cycle_state": "FINANCIAL",
                "title": "Ms",
                "type": "PERSON",
                "first_name": "First Name",
                "name": "First Name Last Name",
                "id": "123456789",              
                "demographics":
                {
                    "gender": "MALE",
                    "passport_number": "123456",
                    "social_security_number": "123456",
                    "date_of_birth":
                    {
                        "month": 1,
                        "day": 1,
                        "year": 1990
                    },
                    "name_day":
                    {
                        "month": 5,
                        "day": 5
                    },
                    "id_number": "123456"
                }
            },
            "life_cycle_state": "ACTIVE",
            "number": "400",
            "name": "First Name Last Name",
            "id": "123456789"
        }       
        "id": "12345678"
      }
  },
  "status": {
    "code": "OK",
    "description": "",
    "message": ""
  }
}

 

Example of POS System spend request form

  1. The following information is displayed
    1. The amount that can be requested to be spent on that transaction (wallet.balance)

Step 4 - Reducing & closing the sales transaction

  1. 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
    1. 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)

    2. 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)
  2. 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
  3. Upon completion, the following information is displayed and printed on the customer's receipt
    1. The amount that was awarded for that purchase, which is the total_awarded_amount retrieved by the POST customer_events/purchases/create used above
    2. 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

  1. 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
  2. There are three ways to identify a customer (referred as rewards participant in CRM.COM):
    1. id: The rewards participant's id is provided
    2. number: The rewards participant's number is provided
    3. 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
  3. Once the customer is identified then the following customer information, which is returned by the Web API, is displayed on the POS
    1. accounts_receivable.account_owner.name: The name of the customer
    2. wallet.balance: The wallet balance of the customer

 

Customer identification Web API example

POST Request
https://hostname/crmapi/rest/v2/rewards_participants/show
Body
{
  "token": "{{token}}",
  "rewards_participant_identifier":{"access_token_identifier":{"authentication_code":"test@crm.com"}},
  "fields_set":"accounts_receivable,wallet"
}
Response
{
    "status":
    {
        "message": null,
        "description": null,
        "code": "OK"
    },
    "data":
    {
      "wallet": {
      "number": "W0000000001",
      "balance": "5.00",
      "currency": {
        "suffix_symbol": "N/A",
        "prefix_symbol": "€",
        "decimal_part_name": "cents",
        "code": "EUR",
        "integer_part_name": "euro",
        "id": "2"
      },       
        "accounts_receivable":
        {
            "account_owner":
            {
                "last_name": "Last Name",
                "life_cycle_state": "FINANCIAL",                 
                "title": "Ms",
                "type": "PERSON",
                "first_name": "First Name",
                "name": "First Name Last Name",
                "id": "123456789",
                "demographics":
                {
                    "gender": "MALE",
                    "passport_number": "123456",
                    "social_security_number": "123456",
                    "date_of_birth":
                    {
                        "month": 1,
                        "day": 1,
                        "year": 1990
                    },
                    "name_day":
                    {
                        "month": 5,
                        "day": 5
                    },
                    "id_number": "123456"
                }
            },
            "life_cycle_state": "ACTIVE",
            "number": "400",
            "name": "First Name Last Name",
            "id": "123456789"
        }       
    }
}

 

Example of POS System after the customer identification

  1. Customer is being identified providing his/her identifier (email address, card number, phone number, mobile app code etc.)

  2. Once the customer is identified then the customer name and available wallet balance are displayed on the POS

Step 2 - Previewing rewards information

  1. 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
  2. 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

POST Request
 https://hostname/crmapi/rest/v2/customer_events/purchases/preview
Body
{
  "token": "{{token}}",
 "accounts_receivable_identifier":{"number":"1234"},
  "classification_identifier":{"name":"Purchase Classification"},
  "performed_by_unit_identifier":{"name":"Unit"},
  "performed_on":"2017-06-22T15:00:00",
  "reference_number":"RF000001",
  "total_amount":20,
  "net_amount":16,
  "vat_amount":4,
  "invoice_identifier":{"number":"I123"},
  "payment_medium_brand_identifier":{"name":"VISA"},
  "payment_medium_type_identifier":{"alternative_code":"CC"},
  "payment_medium_identifier":"PI000001",
  "products_set":
  [
    {
      "product_identifier":{"code":"Soft Drinks"},
      "quantity":1,
      "total_amount":10,
      "net_amount":8,
      "vat_amount":2
    },
    {
      "product_identifier":{"code":"Sandwiches"},
      "quantity":1,
      "total_amount":20,
      "net_amount":26,
      "vat_amount":4
    }
  ]
}
Response
 {
  "data": {
    "total_additional_spend_amount": 11,
    "minimum_spend_amount_per_transaction": 5,
    "total_instant_spend_amount": 2,
    "total_automatic_spend_amount":0,
    "total_award_amount": 3,
    "maximum_spend_amount_per_transaction": 200,
	"reduction_method": FRONT_END_REDUCTION
  },
  "status": {
    "code": "OK",
    "description": "",
    "message": ""
  }
}

 

Example of POS System while previewing the sales summary

  1. The following information is displayed

    1. The reduction Method (reduction_method)

    2. The amount to be awarded (total_award_amount)

    3. The amount that will be spend automatically, without the customer's request (the sum of total_instant_spend_amount and total_automatic_spend_amount)
    4. The amount that is available to be spend on that transaction (total_additional_spend_amount)
    5. 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:

  1. The related customer (accounts_receivable_identifier)
  2. The sales transaction's reference number (reference_number)
  3. The sales transaction's date (performed_on)
  4. The sales transaction's merchant (performed_by_unit_identifier)
  5. The sales transaction's total amount (total_amount)
  6. 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
  7. Optionally the identifier of the POS can be specified (external_system)

 

Submit Purchase  Web API example

POST Request
 https://hostname/crmapi/rest/v2/customer_events/purchases/create
Body
{
   "token":"{{token}}",
   "accounts_receivable_identifier":{"number":"001"},
   "classification_identifier":{"name":"Purchase"},
   "performed_by_unit_identifier":{"name":"Unit"},
   "performed_on":"2017-05-22T16:05:00",
   "description":"Create Purchase event",
   "reference_number":"RF0000762",
   "total_amount":20,
   "net_amount":16,
   "vat_amount":4,
   "invoice_identifier":{"number":"I00003203"},
   "payment_medium_brand_identifier":{"name":"VISA"},
   "payment_medium_type_identifier":{"alternative_code":"CC"},
   "payment_medium_identifier":"PI000001",   
   "external_system":"POS",
   "fields_set":"number,id,reference_number,total_amount"
   "products_set":
   [
     {
       "product_identifier":{"code":"Soft Drinks"},
       "quantity":1,
       "total_amount":10,
       "net_amount":8,
       "vat_amount":2
     },
     {
       "product_identifier":{"code":"Sandwiches"},
       "quantity":1,
       "total_amount":10,
       "net_amount":8,
       "vat_amount":2
     }
   ]
 }
Response
{
  "data": {
    "number": "111",
    "total_amount": 20,
    "id": "123456",    
    "reference_number": "RF0000762",
  },
  "status": {
    "code": "OK",
    "description": "",
    "message": ""
  }
}

Step 4 - Spend Request

  1. 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.

    1. Total additional spend amount, which is the amount that can be requested to be spent on that transaction (total_additional_spend_amount)
    2. The minimum spend amount allowed to be spend per transaction (minimum_spend_amount_per_transaction)
    3. The maximum spend amount allowed to be spend per transaction (maximum_spend_amount_per_transaction)
  2. 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

    1. The related purchase customer event that was created above (purchase_customer_request_identifier)
    2. The amount that is requested to be spend (spend_amount)

  3. 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

POST Request
 https://hostname/crmapi/rest/v2/customer_events/spend_requests/create 
Body
{
   "token":"{{token}}",
   "accounts_receivable_identifier":{"number":"001"},
   "classification_identifier":{"name":"Spend Request"},
   "performed_by_unit_identifier":{"name":"Unit"},
   "purchase_customer_request_identifier":{"number":"936"},
   "performed_on":"2017-05-12T11:41:00",
   "description":"Spend Request",
   "spend_amount":10,
   "external_system":"POS",
   "fields_set":"spend_amount,type,number,id,life_cycle_state,performed_on,performed_by_unit,external_system,spend_reward_transaction"
 } 
Response
{
  "data": {
    "number": "294",
    "spend_amount": 10,
    "id": "12345678",
    "life_cycle_state": "POSTED",
    "type": "SPEND_REQUEST",
    "performed_on": "2017-05-12T11:41:00",
    "performed_by_unit": {
      "alternative_code": "U",
      "name": "Unit",
      "description": Unit,
      "id": "12345678"
    },
    "external_system": "POS",
    "spend_reward_transaction": {
      "number": "01",
      "vat_amount": 0,
      "total_amount": 10,
      "id": "12345678",
      "net_amount": 10,
      "life_cycle_state": "POSTED",
      "rewards_participant": {
        "number": "001",
        "accounts_receivable":
        {
            "account_owner":
            {
                "last_name": "Last Name",
                "life_cycle_state": "FINANCIAL",
                "title": "Ms",
                "type": "PERSON",
                "first_name": "First Name",
                "name": "First Name Last Name",
                "id": "123456789",              
                "demographics":
                {
                    "gender": "MALE",
                    "passport_number": "123456",
                    "social_security_number": "123456",
                    "date_of_birth":
                    {
                        "month": 1,
                        "day": 1,
                        "year": 1990
                    },
                    "name_day":
                    {
                        "month": 5,
                        "day": 5
                    },
                    "id_number": "123456"
                }
            },
            "life_cycle_state": "ACTIVE",
            "number": "400",
            "name": "First Name Last Name",
            "id": "123456789"
        }       
        "id": "12345678"
      }
  },
  "status": {
    "code": "OK",
    "description": "",
    "message": ""
  }
}

 

Example of POS System spend request form

  1. The following information is displayed
    1. The amount that can be requested to be spent on that transaction (total_additional_spend_amount)
    2. The minimum spend amount allowed to be spend per transaction (minimum_spend_amount_per_transaction)
    3. The maximum spend amount allowed to be spend per transaction (maximum_spend_amount_per_transaction)

Step 5 - Reducing & closing the sales transaction

  1. 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
    1. 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

    2. 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
  2. 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
  3. Upon completion, the following information is displayed and printed on the customer's receipt
    1. The amount that was awarded for that purchase, which is the total_award_amount retrieved by the POST customer_events/purchases/preview used above
    2. 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

  1. 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
  2. There are three ways to identify a customer (referred as rewards participant in CRM.COM):
    1. id: The rewards participant's id is provided
    2. number: The rewards participant's number is provided
    3. 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
  3. Once the customer is identified then the following customer information, which is returned by the Web API, is displayed on the POS:
    1. accounts_receivable.account_owner.name: The name of the customer
    2. wallet.balance: The wallet balance of the customer

 

Customer identification Web API example

POST Request
https://hostname/crmapi/rest/v2/rewards_participants/show
Body
{
  "token": "{{token}}",
  "rewards_participant_identifier":{"access_token_identifier":{"authentication_code":"test@crm.com"}},
  "fields_set":"accounts_receivable,wallet"
}
Response
{
    "status":
    {
        "message": null,
        "description": null,
        "code": "OK"
    },
    "data":
    {
      "wallet": {
      "number": "W0000000001",
      "balance": "5.00",
      "currency": {
        "suffix_symbol": "N/A",
        "prefix_symbol": "€",
        "decimal_part_name": "cents",
        "code": "EUR",
        "integer_part_name": "euro",
        "id": "2"
      },       
        "accounts_receivable":
        {
            "account_owner":
            {
                "last_name": "Last Name",
                "life_cycle_state": "FINANCIAL",
                "title": "Ms",
                "type": "PERSON",
                "first_name": "First Name",
                "name": "First Name Last Name",
                "id": "123456789",              
                "demographics":
                {
                    "gender": "MALE",
                    "passport_number": "123456",
                    "social_security_number": "123456",
                    "date_of_birth":
                    {
                        "month": 1,
                        "day": 1,
                        "year": 1990
                    },
                    "name_day":
                    {
                        "month": 5,
                        "day": 5
                    },
                    "id_number": "123456"
                }
            },
            "life_cycle_state": "ACTIVE",
            "number": "400",
            "name": "First Name Last Name",
            "id": "123456789"
        }       
    }
}

 

Example of POS System after the customer identification

  1. Customer is being identified providing his/her identifier (email address, card number, phone number, mobile app code etc.)

  2. 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:

  1. The related customer (accounts_receivable_identifier)
  2. The sales transaction's reference number (reference_number)
  3. The sales transaction's date (performed_on)
  4. The sales transaction's merchant (performed_by_unit_identifier)
  5. The sales transaction's total amount (total_amount)
  6. 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.
  7. Optionally the identifier of the POS can be specified (external_system)

 

Submit Purchase Web API example

POST Request
 https://hostname/crmapi/rest/v2/customer_events/purchases/create
Body
{
   "token":"{{token}}",
   "accounts_receivable_identifier":{"number":"001"},
   "classification_identifier":{"name":"Purchase"},
   "performed_by_unit_identifier":{"name":"Unit"},
   "performed_on":"2017-05-22T16:05:00",
   "description":"Create Purchase event",  
   "reference_number":"RF0000762",
   "total_amount":20,
   "net_amount":16,
   "vat_amount":4,
   "invoice_identifier":{"number":"I00003203"},
   "payment_medium_brand_identifier":{"name":"VISA"},
   "payment_medium_type_identifier":{"alternative_code":"CC"},
   "payment_medium_identifier":"PI000001",   
   "external_system":"POS",
   "fields_set":"number,id,reference_number,total_amount"
   "products_set":
   [
     {
       "product_identifier":{"code":"Soft Drinks"},
       "quantity":1,
       "total_amount":10,
       "net_amount":8,
       "vat_amount":2
     },
     {
       "product_identifier":{"code":"Sandwiches"},
       "quantity":1,
       "total_amount":10,
       "net_amount":8,
       "vat_amount":2
     }
   ]
 }
Response
{
  "data": {
    "number": "111",
    "total_amount": 20,
    "id": "123456",    
    "reference_number": "RF0000762",
  },
  "status": {
    "code": "OK",
    "description": "",
    "message": ""
  }
}

Step 3 - Reducing & closing the sales transaction

  1. 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:
    1. Award the purchase customer event with any applicable awards
    2. Reduce the wallet balance by the amount of money that can be automatically spend by the customer on that purchase
    3. Refund that money through a payment gateway such as Paypal
    4. Send an email and/or SMS to the customer informing him / her about the awards and refunds that were applied
  2. 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

  1. The Sales Transaction is canceled through the POS System
  2. The related to the sales transaction, Purchase Customer Event is also canceled through the Web API POST customer_events/purchases/cancelIf 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

POST Request
https://hostname/crmapi/rest/v2/customer_events/purchases/cancel
Body
{
  "token": "{{token}}",
  "customer_event_identifier":{"number":"111"},
  "fields_set":"number,life_cycle_state"
}
Response
{
    "status":
    {
        "message": null,
        "description": null,
        "code": "OK"
    },
    "data":
    {
      "number": "111",
      "life_cycle_state": "CANCELLED"
	}
}

Additional Documentation

Visit CRM.COM Manuals in order to find more information related to the areas / concepts mentioned in above scenarios

ModuleDescriptionManuals' Link
Rewards ParticipantManage the customers who have signed up for Rewards or have been automatically selected to participateManaging 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
Reward Participating Merchants contribute to the amount awarded to Rewards Participants, based on rules which are agreed and defined between the Merchant and the business

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

  • Define a financial amount to be awarded to Rewards Participants, based on their actions
  • Define the conditions for an Award to be given
  • Define the conditions that should be met for the awarded amount to be spent
Managing Rewards Offers
Purchase Customer EventsEvents linked with the purchase of goodsPurchase Customer Event
Spend Request Customer EventsEvents linked with the spending of Award points of ParticipantsSpend Request Customer Event
Access TokensAccess Tokens are used to identify and authenticate customersManaging Access Tokens
ProductsProducts are goods that used by business transactions in the SystemManaging Products