Description of the API methods is available at docs.uds.app
Workflow for the POS system integrated with UDS:
The customer downloads the UDS App
The customer shows the QR code from the application to the cashier
The cashier enters this code to the POS system and information about the customer is displayed (Name, Last name, number of accumulated points)
The cashier enters the number of points to be deducted, 1 point = $1
The total purchase amount is reduced by the number of points to be deducted. For example, the purchase amount is $10, 3 points are to be deducted, in total the customer is left to pay $7
After payment, information about this payment is sent to UDS
If for some reason the payment is made without using UDS, print the voucher for the customer to get points after the purchase.
Detailed instructions with methods
Requirements:
The API key (token) and company id used for POS integration should not be hardcoded. It means that when setting up the integration module, it should be possible to register the API key and id in some configuration file (config), because they are different for every company.
Important! If a 403 forbidden error is returned when sending requests, the API key or company id is incorrect. |
The documentation for configuring this module should be available with the integration module, i.e. so that any cash system specialist could set up integration in the company.
Potential business process for the POS system with implemented integration with UDS:
1. After generating the final bill for payment, it should be possible to enter the customer code from the UDS App (promo.uds.app) or the customer’s phone number in the international format +79992221133. If possible, it is also better to implement the feature to enter the customer code using a QR code scanner.
2. After entering the code or phone number of the customer, the integration module sends a request to the UDS server and displays information about the customer from the response from the server (get request “find customer”, see docs.uds.app documentation):
curl -H 'Accept: application/json' \ |
where code – customer’s code from the UDS App,
total – initial bill amount (excluding discounts and points to be deducted).
Response:
uid – user ID (it can also be used for search and payments)
displayName – first and last name
discountRate – discount rate
points – number of points
netDiscount – total number of points available for redemption
code – code for conducting a transaction
If, when entering a phone number, information about the customer is not returned (notFound), this means that this customer is not registered in the UDS App yet. In this case you should add a phone number to the order, transactions for unregistered phone numbers should also be carried out.
3. A discount is applied to the order in the amount of discountRate. If discountRate=0, it means that the customer will receive points after payment and the discount is not needed. Important! The discount can be applied only if the request was sent using the customer code, the discount cannot be applied by phone number or uid.
4. Enter the number of points to deduct (no more than maxPoints). If maxPoints = 0, entering the number of points to be deducted should be unavailable.
Important! Points always may be deducted when entering the code from the application. Points may be deducted by phone number if the corresponding feature is switched on in the company settings. Points can be accrued by uid, but not deducted.
5. The total bill amount is reduced by the applied discount (in case of discount, not reward) and the number of points to be deducted.
6. After clicking the Pay button (closing the order), the transaction should also be sent to UDS (Create operation, see documentation at docs.uds.app).
Request example:
curl -H "accept: application/json" \ -H "Content-Type: application/json" \ |
Create operation request sends the following parameters:
code (code for transaction verification, from the response to Find customer request) or phone (phone number in the international format)
total (initial bill amount, including promo items)
points (number of points to be deducted). Deduction by phone number is not available, i.e., 0 should be indicated for points parameter
cash (amount paid in cash (card/cash/their combination))
ExternalId and name (identifier and name of the cashier who performed the transaction. In the POS system, the id or number of the employee can be the identifier. Externalid can only consist of numbers and Latin letters)
number (bill number in the POS system)
skipLoyaltyTotal (amount of items value, on which the loyalty program terms don't apply. For example, the amount of promo items)
If an error is returned from UDS, do not perform payment in the POS system until the error is eliminated, i.e. make payment only after receiving a success response. Possible errors are described below.
If an error from UDS returned during payment/completion of the order, indicate the appropriate description in the POS interface:
Status | Error code | Description |
400 | badRequest | Form validation errors occurred. Contact POS system developers |
400 | invalidChecksum | Delete other discounts from the order |
400 | insufficientFunds | Attempt to deduct more points than the customer has. Correct the request |
400 | discountLimitExceed | Attempt to deduct points more than allowed by marketing terms. Correct the request |
403 | companyIsInactive | The company is not active. Renew your UDS subscription |
404 | notFound | Invalid customer code or it has expired. Enter a new customer code |
404 | cashierNotFound | Invalid identifier in cashierExternalId. Only numbers and latin letters without spaces are allowed |
Implement the feature to cancel a payment, i.e. if cancelled in the POS system, the transaction shall also be cancelled in UDS. Refund request with UDS transaction id, the value of which is returned as a response after a successful transaction.
To implement a partial payment cancellation, it is necessary to send the partialAmount parameter (amount by which the cancellation is made) in this request.
Request:
curl -H "accept: application/json" \ |
You should provide the possibility of printing a voucher for customers to accumulate points.
The method allows printing a voucher code (QR code) on the bill, and the customer will be able to receive points for the purchase by scanning it in the UDS App. For example, the customer forgot its smartphone, there was no time, the employee didn’t tell about the opportunity to accumulate points, etc., the customer will be able to get points later from the bill with such a voucher. The voucher is valid for 3 hours.
Important! A prerequisite for using this functionality is to configure the loyalty program add-on in the settings of the UDS Business panel (https://admin.uds.app/). Select "Accrue points" in the "Discounting method" setting and indicate more than 0 for the base status.
Endpoint
Method - POST
Creation of a voucher for a transaction in UDS. If successful, you will receive information to print the code and a link for a graphical display of the voucher QR code on the bill.
Sample request to send for creating a voucher:
curl -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Origin-Request-Id: $(uuidgen)" \ -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \ -u "<companyId>:<api_key>" -d '{ \ "nonce":"string-UUID", \ "cashier":{ \ "externalId":"string", \ "name":"string" \ }, \ "receipt":{ \ "total":100.0, \ "number":"string", \ "skipLoyaltyTotal": 50.0 \ } \ }' -X POST "https://api.uds.app/partner/v2/operations/voucher" |
The following parameters should be passed in the Voucher request:
• total (initial bill amount); If the order contains other discounts, the total amount shall be indicated when these discounts are applied.
• skipLoyaltyTotal – amount for which reward is not credited. If the order contains items that should not be covered by the UDS loyalty program (i.e., discounts do not apply to these items), you need to pass their amount in this parameter.
• externalId и name – identifier and name of the cashier who performed the transaction. In the POS system, the id or number of the employee can be the identifier. Externalid can only consist of numbers and Latin letters)
• number (bill number in the POS system);
Response
VoucherInfo{
code | string Voucher numeric code |
qrCodeText | string Text to generate a QR code voucher for further printing |
qrCode128 | string Link to generate a QR code image (size 128) that can be printed. |
qrCode256 | string Link to generate a QR code image (size 256) that can be printed. |
expiresIn | string($date-time) Time when the voucher expires (UTC) |
points | number The number of points to be awarded is calculated from the settings of the base level of the loyalty program. If a customer with the higher level scans a bill, points will be credited according to its level. |
}
Return error
Status | Error Code | Description |
400 | invalidChecksum | Discount, not reward (CHARGE_SCORES) |
400 | invalidChecksum | The total, skipLoyaltyTotal fields do not correlate with the company's marketing settings |
400 | invalidChecksum | The amount of points to be accrued is 0 |
400 | invalidChecksum | The total field is less or equals to skipLoyaltyTotal |
xtagendz
xtagendz