Usage Of The inCust Terminal API

  1. General information
  2. Authorization
    2.1 Authorize using login and password
    2.2 Authorize using API KEY
  3. Receive Terminal settings
  4. Receive customer categories
  5. Receive customer accounts
  6. Receive goods and categories
  7. Receive customer data
    7.1 Receive customer identifier from inCust Kiosk
    7.2 Receive customer questionnaire
    7.3 Change customer questionnaire
    7.4 Change customer's access type
    7.5 Change customer's category
    7.6 Customer's consent to processing of personal data
  8. Receive loyalty program rules
  9. Operations with check
    9.1 Check preparation
    9.2 Check processing
    9.3 Save check with finalization
    9.4 Save check
    9.5 Reserve check
    9.6 Finalize check
    9.7 Create and finalize check
    9.8 Reserve funds for check
    9.9 Processing of check with previously reserved funds
    9.10 Write off previously reserved funds
  10. Payments
    10.1 Query payments by check
    10.2 Add payment to check
    10.2 Cancel payment by check
    10.4 Send information about payment to app for customers
    10.5 Retrieve payment status
  11. Transactions
    11.1 Transaction object
    11.1 Receive list of transactions
    11.2 Cancel transaction
    11.3 Receive information about transaction
    11.4 Receive check of transaction
  12. Code of order
    12.1 Generate code of order
    12.2 Retrieve code of latest order, generated by Temrinal
  13. Customer identifiers
    13.1 Search for customers by identifiers
    13.2 Register 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 series
    14.2 Retrieve coupon data
    14.3 Use coupon without customer
    14.4 Get list of coupons, added to customer's wallet
    14.5 Add coupon to 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. Store
    17.1 List of customer's orders
    17.2 List of orders
    17.3 Retrieval of information about order
    17.4 Change of order status
  18. Jobs
    18.1 Job object
    18.2 Query jobs by check
    18.3 Create job and link it to check
    18.4 Create job
    18.5 Obtain information about job
    18.6 Start job
    18.7 Stop job
    18.8 Link existing job to check
  19. Fuel and energy
    19.1 Detailed information about state of fuel pump or charging station
  20. Goods and categories in brand
    20.1 Retrieve goods list
    20.2 Create goods
    20.3 Retrieve goods categories list
    20.4 Create goods category
    20.5 Obtain information about goods category
    20.6 Change goods category
    20.7 Add or change goods category image
    20.8 Retrieve goods by code
    20.9 Retrieve goods by ID
    20.10 Change goods
    20.11 Activate/deactivate goods
    20.12 Add supplementary goods image
    20.13 Delete supplementary goods image
    20.14 Add main goods image
    20.15 Add recommended values for goods
    20.16 Add price list for goods
  21. Additional functions
    21.1 Confirmation of customer's phone number
  22. 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 Terminal API, you need to use the authorization token, which should be added to the header of all requests.

The token can be short-term, when it is obtained using the login and password, and long-term, when it is obtained via the API KEY.

Before you get to authorization, you need to add at least one Terminal to the list of Terminals in the Business Control Panel. The login and password as well as the API key of one of the added Terminals will be used for authenticating API requests.

Authorization using login and password

To work with the Terminal API using the login and password, one needs to receive an authorization token. This token is to be added to the header of all requests. The login and password should match the values set for one of the Terminals which you have added in the Business Control Panel.

Request for authorization token

Authorization using API KEY

To authenticate requests to the Terminal API, you can use API KEY instead of the token. You can enable authentication with an API KEY in the Business Control Panel - use the API KEY button near the name of the Terminal entry, which you want to use for API operations.

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

Advantages of the API KEY authorization method:


Receiving Terminal settings

Request for retrieval of Terminal settings

Receive customer categories

To change a customer's category, it is necessary to load the list of available categories.

Request for receiving customer categories

Receiving of customer accounts

In order to work with customer accounts (provision of a free cup of coffee after buying seven cups, getting prepaid volume of fuel, etc.) in the inCust Terminal, you must retrieve accounts, available to the Terminal. If you don't expect 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 Terminal.

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 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 the platform.

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

Change customer's category

This method allows to change the customer's category.

Request for changing the customer's category

The method lets you record the customer's consent to use the platform services and to allow storage and processing of personal data.


The customer consent object has the following fields:


Receiving loyalty program rules

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

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 method
If the saved check is not finalized within two hours, it is cancelled automatically, and all reserved money are released.

Request for check saving

Reserve check

To reserve funds and lock payments for a longer period (up to one month), it is necessary to reserve the check. Before sending the check to saving, it is required to process the check object with check processing method
If the reserved check is not finalized within one month, it is cancelled automatically, and all reserved money are released.

Request for check saving

Finalize check

Finalization of the previously saved or reserved 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

Reserve funds for check

The operation lets one reserve funds on a customer account or a bonus points account of a customer, or, if the payment is done via the mobile app, on a bank card of a customer. Before sending a check for finalization it is necessary to process the check object with the check processing method.
The funds are reserved until they are written off by the Write off of the previously reserved funds operation and become unavaialble for further use in other operations.
The funds are reserved for the term up to seven days, after which, if the check has not been finalized and the funds have not been written off, they are released for further use.

Request to reserve funds for check

Processing of check with previously reserved funds

Calculation of funds (discounts, credited bonus points, and amounts credited on customer accounts) which were previously reserved for the check by the Reserve funds for check operation.

Request for check processing

Write off previously reserved funds

The operation of writing off the funds, previously reserved for the check by the Reserve funds for check operation.
The amount of funds that will be written off must not exceed the reserved amount, but can be lower. This way, the data of the check can be altered but only to reduce the cost and the sum of the funds being written off.

Request to write off previously reserved funds

Payments

In the inCust platform, 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

Terminal 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

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

Retrieval of payment status

Transactions

The section contains descriptions of all operations with transactions


Transaction object

The object contains the general information about the transaction


Receiving a list of transactions

Request for receiving a list of transactions

Cancellation of transaction

Request for cancellation of transaction

Receive information about the transaction

request to receive information about the transaction

Receive check of the transaction

Receiving of the object with the check, based on which the transaction was created.

Request to retrieve information about check of the transaction

Code of the order

Code of the order is the temporary code, generated by the Terminal app 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

Terminal 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 Terminal app in Steward mode

Terminal lets you obtain the latest code, generated by Terminal app in Register or Steward modes that works under the same account as the given Terminal.

Request for the latest code, generated by Terminal app in Steward mode

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., Terminal 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

Terminal can add a customer record to inCust system, using the set of identifiers of the customer, such as phone number, email address, social network ID etc.

Request for addition of customer with specified identifiers

Retrieval of customer identifiers

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

Request for retrieval of customer identifiers

Addition of customer identifiers

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

Request for addition of customer identifiers

Removal of customer identifiers

Terminal 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

List of coupons, added to 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 customer wallet

Request for adding coupon to 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 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 (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

Store

The loyalty program can have the Store activated. In this store, customers can place orders using the mobile app.
With the help of the Terminal API, orders can be processed, shipped or canceled.


An Order object contains the following fields:


List of customer's orders

Paginated list of customer's orders, filtered by date and payment status.

Request to retrieve the list of a customer's orders

List of orders

Paginated list of orders, filtered by date and payment status.

Request to retrieve the list of orders

Retrieval of information about the order

Information about the order

Request for retrieval of order data

Changing the order status

The Terminal API lets you change the status of the order

Request to change the order status

Jobs

In the inCust system, it is possible to define jobs for external modules and devices (Fuel station pumps, charging stations, parkings etc.).
Jobs can be linked to a check or be an independent object, which can be linked to a check later.


Job object

A job is a complex object, the data of which depend on the type (fuel delivery, electric charging etc.) of the job being executed.


Querying of jobs by check

One can retrieve the list of jobs, linked to the check.

Querying of jobs by check

Creation of job and linking it to check

It is possible to create jobs and link them to a previously created check.

Request for creation of of job and linking it to check

Creation of job

A job can be created as an independent object that can be linked to a check later.

Request for creation of job

Information about job

This method returns information about the job

Request for information about job

Starting of job

This method starts processing of the previously created job.

Request for starting of job

Stopping of job

The method forcefully stops the job

Request for stopping of job

Linking of existing job to check

An earlier created job, not linked to the check, can be linked to the existing check at any moment of time.

Request for linking of existing job to check

Fuel and energy

In the inCust platform, one can plug external controllers, which manage fuel pumps and charging stations.


Detailed information about state of fuel pump or charging station

This method returns detailed information about the state of the fuel pump or charging station, connected to this Terminal.

Request for detailed information about state of fuel pump or charging station

Goods and categories in brand

Using Terminal API, you can create and update goods and categories within the brand.


Retrieve goods list
Create goods
Retrieve goods categories list
Create goods category
Obtain information about goods category
Change goods category
Add or change goods category image
Retrieve goods by code
Retrieve goods by ID
Change goods
Activate/deactivate goods
Add supplementary goods image
Delete supplementary goods image
Add main goods image
Add price list for goods

Additional functions


Confirmation of customer's phone number

This method is used to verify that the phone number, provided by the customer, really belong to this customer.
The procedure consists of two steps:

  1. Sending of the confirmation code via SMS to the phone number
  2. Validation of the confirmation code, specified by the customer.
Request to send the SMS with the confrmation code
Request for validation of the confirmation code, received from the customer

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 record is suspended
8 Customer record 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
14 Customer record is blocked
15 Customer record is deleted
16 User consent required
18 Error during image transfer
20 PIN generation failed
21 PIN sending failed
22 PIN is required
25 A customer record with such phone number already exists
26 A customer record with such email already exists
27 Customer record suspended because of sending invalid requests
28 A customer record with such ID already exists
30 Business not found
31 Customer not found
32 Referral code not found
33 Customer record 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
45 Error of the referral program
46 Referral code not found
47 Delivery type not found
48 Store not found
49 Error in delivery information
50 Point of Sale not found
51 Order not found
52 The order already has a transaction
60 Terminal not found
61 Temrinal disabled
62 Such Terminal's or salesperson's phone number already exists
63 Terminal does not use a password. Use the API KEY for access.
64 Terminal phone number not set
65 Terminal 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.
103 Erroneous transaction type
104 Transaction registered for another customer
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
132 EMail 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
149 Operation not applicable to the specified type of coupon series
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 The 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
268 It is not possible to execute a payment with a mobile app without a customer
270 Job not found
271 Job already linked to the transaction
272 The transaction already has linked jobs
273 The transaction has incomplete jobs
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 Terminal or salesperson's login already exists
9005 Such Terminal or salesperson's phone number already exists
9006 inCust Terminal 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 Terminal or salesperson is 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 record is inactive. Waiting for confirmation.
9021 Transaction error. Customer is not entitled to redeem bonus points.
9022 Transaction error. Customer record is suspended.
9023 Transaction error. Customer record is disabled.
9024 Bonus points account of the customer not found
9025 Referral code not found
9026 Customer records 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 record 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
9060 Referral program not active
9061 The limit of referral codes emission has been exceeded
9062 Application not found or not active
9063 Order not found
9064 Customer record is blocked
9065 Customer record is deleted
9066 Parameter not found
9067 A customer with such phone number already exists
9068 A customer with such email address already exists
9069 Transaction error. It is not possible to write off more funds that were authorized before.
9997 Functionality under development
9998 Insufficient funds on inCust account. To continue, please, replenish inCust account in the Control Panel.
9999 General SQL error