Usage Of The inCust Register API

  1. General information
  2. Authorization
    2.1 Authorize using login and password
    2.2 Authorize using API KEY
  3. Receive Register settings
  4. Receive customer accounts
  5. Receive goods and categories
  6. Receive customer data
    6.1 Receive the customer identifier from inCust Kiosk
    6.2 Receive the customer questionnaire
    6.3 Change customer questionnaire
    6.4 Change customer's access type
  7. Receive loyalty program rules
  8. Operations with check
    8.1 Check preparation
    8.2 Check processing
    8.3 Save check with finalization
    8.4 Save check
    8.5 Finalize check
    8.6 Create and finalize check
  9. Payments
    9.1 Query payments by check
    9.2 Add payment to check
    9.2 Cancel payment by check
    9.4 Send information about payment to app for customers
    9.5 Retrieve payment status
  10. Receive the list of transactions
  11. Cancel transaction
  12. Code of the order
    12.1 Generate the code of the order
    12.2 Retrieve the code of the latest order, generated by Register or inCust Steward
  13. Customer identifiers
    13.1 Search for customers by identifiers
    13.2 Register the customer with specified identifiers
    13.3 Retrieve customer identifiers
    13.4 Add customer identifiers
    13.5 Remove customer identifiers
  14. Coupons
    14.1 Issue coupons of the series
    14.2 Retrieve coupon data
    14.3 Use coupon without customer
    14.4 Get the list of coupons, added to the customer's wallet
    14.5 Add coupon to the customer wallet
    14.6 Ust coupon of "certificate" type
  15. Benefits
    15.1 Crediting of customer account
  16. Tourist card (prepaid services card)
    16.1 List of customer's tourist cards
    16.2 Add tourist card to customer's wallet
    16.3 Retrieval of data about tourist card
    16.4 Use of service from tourist card
  17. Response codes

General information

Exchange of information with the API server is performed in JSON format

Server URL: https://api.incust.com/v1

In the header of any request, the following fields should be present:

Authorization

To use the Register, you need to use the authorization token, which should be added to the header of all requests.

The token can be short-term, when received using the login and password, and long-term, contained in the API KEY.

Authorization using login and password

To work with Register using the login and password, one needs to receive the authorization token, which will be then added to the header of all requests.

Request for authorization token

Authorization using API KEY

To authorize the requests to Register, you can use API KEY instead of the token. You can enable authentication with API KEY in the Control Panel, the API KEY button near each register's name.

The format of the Authorization field in the header is the same as in the case of a token, obtained using login and password: "Authorization":"bearer eyJ0ZXJtaW5hbF9pZCI6IjAyYmE2YmVhLWVjZjMtMTFlNS1hODNhLTAyMDAwMGVkMTQ3ZCIsInZlcnNpb24iOjF9.C5rXRQ.FVbaHN0go0FK3EbWIXtEg9AvNbg"

Advantages of API KEY:


Receiving Register settings

Request for retrieval of Register settings

Receiving customer accounts

In order to work with special accounts of customers (issuing a cup of coffee after buying 7 cups, getting prepaid litres of gasoline, etc.) in the inCust Register, you must obtain accounts, available to the Register. If you are not supposed to work with accounts, you can skip this step and go directly to the receiving of goods and categories

Request for receiving customer accounts

Receiving goods and categories

After successful authorization, it is necessary to obtain a list of goods and categories of goods for conducting trading operations in the inCust Register.

Receiving a list of categories
Receiving the list of goods

Receiving customer data

This method is necessary to obtain information about the customer: the number of bonus points on the account, the availability of funds in the accounts of the customer, the name, age data, etc.

Request for receiving customer data

Receiving the customer identifier from inCust Kiosk

this method allows to get the customer ID from the Kiosk application and a one-time password (PIN) from the SMS, which is necessary for redeeming bonus points and charging customer accounts. Read more inCust Kiosk, customer self-service

Request for receiving the customer identifier from inCust Kiosk

Receiving customer's questionnaire

This method allows to get customer's profile data which are stored in inCust.

Request for receiving customer's questionnaire

Changing customer`s questionnaire

This method allows to update the data of the customer's questionnaire.

Request for changing the customer`s questionnaire

Change customer's access type

This method allows to change the type of customer's access.

Request for changing the customer`s access type

Receiving loyalty program rules

This method is required in order to receive a list of the loyalty rules, available for manual application.

Request for receiving the loyalty program rules

Operations with check

The section contains descriptions of all steps of check processing.


Check preparation

Before processing a check it needs to be formed. The example of a check and the required fields are described below.


Check processing

To calculate the amount of discounts / credits of bonus points / credits to a customer account, you need to perform a check processing operation. The operation of processing a check is MANDATORY, it must be performed before sending a check for finalization

Request for check processing

Saving of check with finalization

To complete the operation, it is necessary to finalize (save and close) the check. Before sending a check for finalization it is necessary to process the check object with the - check processing method.

Request for check finalization

Save check

To reserve the funds and complete payments of the operation, it is necessary to save the check. Before sending the check to saving, it is required to process the check object with - [check processing] (#register-check-processing) method If the saved check is not finalized within 2 hours, is is cancelled automatically, and all reserved money are released.

Request for check saving

Finalize check

Finalization of the previously saved check

Request for finalization of the check

Create and finalize check

Operation of check creation with finalization. Includes the complete cycle of check processing with creation, writing and finalization.

Request for check creation with finalization

Payments

In inCust, it is possible to link payments to the check.


Query payments by check

It is possible to retrieve the list of pyaments, linked to the check.

Querying payments by check

Add payment to check

It is possible to link the payment to the check.

request for adding payment to check

Cancel payment by check

It is possible to cancel the payment, previously linked to the check.

Request to cancel the payment by check

Sending of information about payment to app for customers

Register can send the information about the payment to the app for customers

Request for sending of information about the payment to the app for customers

Retrieval of payment status

Register can request the status of the mobile payment by transaction or check.

Retrieval of payment status

Receiving a list of transactions

Request for receiving the list of transactions

Cancellation of the transaction

Request for cancellation of the transaction

Code of the order

Code of the order is the temporary code, generated by Register or inCust Steward application, that lets one identify the customer and, when enabled during generation, redeem benefits, such as bonus points and items from customer accounts.


Generation of code of order

The register offers generation of the code of the order. In the case, when the code allows redemption of benefits, it will be sent to the customer. Otherwise, the code will be returned as the response to the request.

Request for generation of code of order

Retrieval of the code of the latest order, generated by Register or inCust Steward

Register lets you obtain the latest code, generated by Register or by the inCust Steward application that works under the same account that Register.

Request for the latest code, generated by inCust Steward app

Customer identifiers

Each customer has one or several identifiers, such as such as phone number, email, social network ID, plasctic card number etc.


Searching for customers by identifiers

When having the identifier or several identifiers, such as phone number, email, social network ID etc., Register can search for customers in the inCust system, whose records match the identifiers. If several specified identifiers belong to different accounts, all accounts that include at least one of the specified identifiers will be returned.

Request for searching for customers by identifiers

Registration of customer with specified identifiers

Register can add a customer account to inCust system, using the set of his/her identifiers, such as phone number, email address, social network ID etc.

Request for addition of customer with specified identifiers

Retrieval of customer identifiers

Register can retrieve all customer's identifiers in the inCust system.

Request for retrieval of customer identifiers

Addition of customer identifiers

Register can add identifiers to the customer's record in the inCust system.

Request for addition of customer identifiers

Removal of customer identifiers

Register can remove some identifiers, such as plastic card numbers and alike, from the customer record in the inCust system

Request for removal of customer identifiers

Coupons

Operations with coupons


Issue coupons of the series

Issuing of coupons by the specified series. The issued coupons are not added to the customer's wallet.

Requet to issue coupons of the series

Retrieve coupon data

Retrieval of the data data about coupon by code or external code.

Request to retrieve data about coupon

Use coupon without customer

External coupons can be used without a customer.

Use coupon without customer

The list of coupons, added to the customer's wallet

The list includes all coupons, added to the customer's wallet, which were not redeemed and didn't expire.

Request to receive the list of coupons, added to the customer's wallet

Adding coupon to the customer wallet

Request for adding coupon to the customer wallet

Using coupon of "certificate" type

Coupons of the "certificate" type allows one-time redeeming of reward by the customer. The reward can be bonus points, temporary bonus points (with a limited period of validity), replenishment of the customer's special account.

Using coupon of "certificate" type

Benefits

Benefits are some points or values, which are credited to customer accounts or to the bonus point account of the customer. Bonus points can be temporary (they expire after certain time) or regular, lifetime of which is not limited.


Crediting of customer account

The method lets you credit benefits to the customer's account.

Request for crediting of customer account

Tourist card (prepaid services card)

A tourist card is a virtual card that contains the set of prepaid services.

A tourist card object contains the following fields:

- **id**: id of a tourist card
- **code**: tourist card code
- **public_title**: public title of the card
- **public_description**: public description of the card
- **image**: card image, the link to the picture
- **active**: the flag that specifies if the card has been activated
- **activated_dt**: date and time of activation in `'YYYY-MM-DD HH-mm-ss'` format
- **expire_dt**: date and time of expiration in `'YYYY-MM-DD HH-mm-ss'` format
- **valid**: the flag that specifies if the card is valid
- **accounts**: the array of account objects; contains information about accounts, available with the card; each account object contains the following fields 
    - **id**: id of the account
    - **public_title**: public name of the account
    - **precision**: precision of the acount, the possible values are `'integer'`, `'two-decimal-places'`, `'three-decimal-places'`  
    - **amount**: account balance
- **services**: array of the service objects; contains information about services, avaialble with the card; each service object contains the following fields
    - **id**: id of the service
    - **public_title**: public name of the service
    - **public_description**: public description of the service
    - **category**: service category object; contains information about the category, to which the service belongs; the service category object contains the following fields
        - **id**: category id  
        - **public_title**: public name of the service category 
    - **decrement_step**: account decrement step
    - **usage_limit_per_loyalty**: limit of the number of uses within the loyalty program (`0` for unlimited use)  
    - **usage_limit_per_loyalty_period_type**: type of restriction period; the possible values are `'all-card-time'`, `'hour'`, `'day'`, `'month'`  
    - **usage_limit_per_loyalty_period_value**: size of restriction period (e.g., when type is set to 'day', 7 stands for a week)
    - **usage_limit_per_pos**: limit of the number of uses within the point of sale (`0` for unlimited use) 
    - **usage_limit_per_pos_period_type**: type of restriction period; the possible values are `'all-card-time'`, `'hour'`, `'day'`, `'month'`  
    - **usage_limit_per_pos_period_value**: size of restriction period (e.g., when type is set to 'day', 7 stands for a week)
    - **used_times**: the number of times the service was used with the card
    - **available_times**: the number of available uses, expected value
    - **available_amount**: account balance
    - **available_now**: availability of the service right now

List of customer's tourist cards

The list includes all tourist cards, present in the customer's wallet.

Request to retrieve the list of tourist cards of the customer

Add tourist card to customer's wallet

This method lets you add a tourist card to the customer's wallet. The method returns the list of tourist cards, added to the wallet.

Request to add a tourist card to the customer's wallet

Retrieval of data about tourist card

Search for the tourist card by code and retrieval of information about this card

Request to retrieve information about the tourist card

Use of service from tourist card

One-time use of the service, available according to the tourist card

Request to use the service from the tourist card

Response codes

Below you will find the list of codes of API responses

Code Description
0 Message returned
1 Failed to create customer record
2 Customer sign in failed
3 Token is not correct
4 PIN is not correct
5 Customer's phone number not found
6 Password not correct
7 Customer's account is suspended
8 Customer's account not found
9 Failed to determine location
10 Database read error
11 Database write error
12 Erroneous field value
13 Mandatory field value is missing
18 Error during image transfer
20 PIN generation failed
21 PIN sending failed
22 PIN is required
25 A customer account with such phone number already exists
26 A customer account with such email already exists
27 Customer account suspended because of sending invalid requests
28 A customer account with such ID already exists
30 Business not found
31 Customer not found
32 Referral code not found
33 Customer account not found
34 No stats available for the specified period
35 Error during redeeming inCust bonus points
36 Business disabled
40 Loyalty program not found
41 Loyalty program rule not found
42 Goods category not found
43 Goods not found
44 Goods with this code already exist
50 Point of Sale not found
60 Register not found
61 Register disabled
62 Such Register's or salesperson's phone number already exists
63 Register does not use a password. Use the API KEY for access.
64 Register phone number not set
65 Register temporarily disabled because of sending requests with invalid parameters
70 Card category does not exist
71 A card with such number is already assigned to another customer
80 Loyalty program rule not found
90 Message not found
100 Transaction not found
101 Error during creation of transaction
102 Insufficient funds on inCust account. To continue, please, replenish inCust account in the Control Panel.
113 Incorrect phone number
114 Card category not found
115 QR code already used or expired
116 Invalid QR code
120 News not found
130 Custom field not found
131 "Phone number" field not set
140 Coupon not found
141 Coupon series not found
142 Unacceptable external code
143 Scanned code does not contain inCust coupon
144 Coupon already used
145 Currency not specified
146 Gift certificate not found
147 Erroneous coupon series specified
148 Gift certificate not valid
150 Invalid or expired link
151 Invalid e-mail or the link has expired
160 Tourist card already linked to another customer
170 Error in check data
171 Erroneous payment type
172 Error in customer account in check
173 Rule not found
174 Not enough funds available on the customer account
180 Shared object not found
181 Sharing of this coupon is not allowed by settings
182 You can't add coupon, which has been shared
185 Wrong benefit type specified
190 The service category of the tourist card has not been found
191 The account of the tourist card has not been found
192 The service of the tourist card has not been found
193 The series of the tourist card has not been found
194 Wrong series of the tourist card
195 Tourist card not found
196 Error when turning off the tourist card
197 Tourist card not valid
198 The tourist card service is invalid or inactive
199 The tourist card service is not available
200 This functionality is not available in your current Service Plan
201 Service plan not found
210 Data amount limit exceeded
220 "Order number" field of the payment not found
230 Currency exchange rate with specified parameters already exists
250 Currency not specified
260 Payment card not found
261 Payment not found
262 Unaccepted payment status
263 Unaccepted sum of payment
264 Wrong password of the payment card
265 Error during payment processing
266 Payment details not found
267 Loyalty program not set up for use of the payment system
280 Social network not supported
281 Social network token is erroneous
282 Authentication in the social network has failed
300 Checkout currently serves another customer
401 Access denied
404 URL not found
500 Server error
9000 Customer not found
9001 Buusiness not found
9002 Loyalty program not found
9003 Point of Sale not found
9004 Such Register's or salesperson's login already exists
9005 Such Register's or salesperson's phone number already exists
9006 inCust Register or salesperson not found
9007 Transaction not found
9008 Coupon not found
9009 Error during cancellation of transaction. Transaction not found.
9010 Transaction has already been canceled
9011 Transaction cancellation error. Bonus points crediting transaction not found.
9012 Transaction cancellation error. Bonus points already redeemed.
9013 Transaction error. Not enough bonus points on account.
9014 Transaction has already been confirmed
9015 Transaction error. It is not possible to redeem bonus points in offline mode.
9016 Transaction error. Currency for the specified inCust Register or salesperson not set.
9017 Transaction error. It is not possible to redeem more bonus points than the sum of the sale.
9018 Transaction error. Transaction of this type cannot be canceled.
9019 Transaction error. Customer is blacklisted.
9020 Transaction error. Customer's account records is inactive. Waiting for confirmation.
9021 Transaction error. Customer is not entitled to redeem bonus points.
9022 Transaction error. Customer account is suspended.
9023 Transaction error. Customer account is disabled.
9024 Bonus points account of the customer not found
9025 Referral code not found
9026 Customer accounts are not found in the account list of your business
9027 Card category not found
9029 Service plan not found
9030 Transaction error. Currency not specified.
9031 Customer account not found
9032 Transaction cancellation error. Insufficient funds on the customer's account.
9033 Specified transaction not found
9034 Transaction error, insufficient funds on the customer's account.
9035 Transaction error. Speicified transaction type cannot be confirmed.
9036 Transaction error. It's not possible to add zero or negative amount of bonus points.
9037 Transaction error. It's not possible to credit account with zero or negative amount.
9038 The monthly sum of bonus points, used to credit the account, must not exceed the total cost of services, used since the beginning of the month.
9039 Coupon series not found
9040 Coupon already used the maximum number of times, set for the coupon series
9041 Coupon already used the maximum number of times, set for one customer
9042 Coupon expired
9043 All external codes have been used
9044 Coupon not found
9045 Scanned code does not contain inCust coupon
9046 Coupon already used by another customer
9047 Currency not specified
9048 Coupon series disabled
9049 Series code used for coupons with unique coupons
9050 Shared object not found
9051 Gift certificate not found
9052 Sharing of this coupon is not allowed by settings
9053 Coupon already used
9054 Customer's account is already linked with the business
9055 Transaction already commited
9056 Tourist cards series has not been found
9057 Tourist card has expired
9058 Tourist card has been issued the maximum amount of times
9059 All tourist card codes have been used
9997 Functionality under development
9998 Insufficient funds on inCust account. To continue, please, replenish inCust account in the Control Panel.
9999 General SQL error