API method documentation is available at: docs.uds.app
Examples of requests in Partner API
The overall business process of the online store remains unchanged. Changes related to UDS integration must be applied to the online store's cart and order issuance. The add-on should be configurable without involving specialists. The company ID and API Key from UDS Business, invitation code, and texts in the cart are set in the add-on settings. Error messages, points deduction/crediting should support multiple languages.
Workflow of an integrated online store with UDS:
- The website administrator can install the add-on independently, specifying the required settings for API access, text displayed to customers, QR code, and the link to join the UDS company.
- The customer downloads the UDS App and joins the company.
- The customer enters the code from the app or phone number in the online store cart.
- Customer information is displayed (First name, Last name, available points). If the customer entered a phone number not registered in the system, display that points will be credited to this number and provide a link to download the app.
- If the company has a discount setting enabled, the cart total is reduced by the discount percentage when a code from the app is entered.
- The customer specifies the number of points to redeem (1 point = 1 CU).
- The final order total decreases by the redeemed points. Example: total 10, redeem 3 points → customer pays 7 CU.
- After the order is created, the operation information is sent to UDS. If UDS is not used for the order, the customer may be shown a QR code and link to get a voucher to earn points after purchase.
Important: Transaction information is sent to UDS immediately after order creation. Therefore, in the loyalty program settings, deferred point accrual (1–15 days depending on order fulfillment time) should be configured.
Proposed business process for the online store with UDS integration:
- Add a UDS Promo Code field in the cart and allow entering the customer code from the UDS App or phone number in international format.
- After clicking “Get Discount”, a GET request is sent to UDS and customer info is displayed (find customer API, see documentation uds.app):
Example request:
curl -H 'Accept: application/json' \
-H "X-Origin-Request-Id: $(uuidgen)" \
-H "X-Timestamp: $(date --iso-8601="seconds" --utc)" \
-u "<companyId>:<api_key>"
-X GET -s https://api.uds.app/partner/v2/customers/find?code=456123&exchangeCode=true&total=1000&skipLoyaltyTotal=300&unredeemabletotal=100
- code – customer code from UDS App
- total – original order amount (without discounts or redeemed points)
- skipLoyaltyTotal – amount excluded from discount/points accrual
- unredeemableTotal – amount on which points cannot be redeemed; the maximum number of points that can be applied is calculated taking this into account
If the order includes external discounts, then the total should be calculated as:
total = original order amount − (external discount × original order amount)
If the order contains products that should not participate in the UDS system (the value of these products should not appear in UDS), then the total should be calculated as:
total = original order amount − cost of excluded products
If the order contains products for which points should not be accrued or discounts applied in UDS, then the value of these products should be passed in skipLoyaltyTotal (amount on which no discount or points accrual applies).
If the order contains products on which points should not be redeemed, then the value of these products should be passed in unredeemableTotal (amount on which points cannot be redeemed).
Response – main fields:
- user -> uid – user ID in the app (can also be used for search and payment)
- user -> displayName – full name
- user -> participant -> discountRate – discount rate
- user -> participant -> points – points balance
- purchase -> maxPoints – total number of points available for redemption
- code – code used for a future transaction with points redemption or discount application (needed in step 8)
- user -> participant -> id – customer ID in this company (needed to determine whether the customer has joined the company)
If the request was made using a code and the response returns a 404 notFound error, display a message stating that the UDS App code is incorrect and a new code must be entered.
If the customer has not joined the company (user -> participant -> id = null), display this information along with a link to join and a QR code.
Applying discount:
Important: Discounts can only be applied when a code from the app is entered; if a phone number is entered, no discount should be applied.
3. Apply a discount to the order equal to discountRate. If discountRate = 0, it means that the customer will receive bonus points after payment and no discount is needed.
If discountRate > 0, the order should receive a discount at the percentage specified by this parameter. In this case, the order total is first reduced by the discount percentage, and then the customer is offered the option to redeem or accrue bonus points.
Redeeming points:
Important: Points redemption is always available when a code from the app is entered. Points can be redeemed using a phone number only if this feature is enabled in the company settings. Points cannot be redeemed using uid; they can only be accrued. To determine the possibility and maximum amount of points that can be redeemed, refer to the purchase -> maxPoints parameter in the customer search response.
4. After this, a “Redeem Points” field should appear, where the number of points to redeem is entered (no more than maxPoints). If maxPoints = 0, the field for entering redeemable points should be disabled.
5. The final order total is reduced by the applied discount (if the company has discounts enabled instead of bonus points) and by the number of redeemed points.
Important: If, for any reason, the cart changes after specifying the number of points to redeem, a new find request must be sent to ensure the customer cannot redeem more points than allowed after editing the cart.
6. After clicking “Place Order”, proceed to the payment form for the remaining amount and to arrange delivery.
7. After submitting the order, a request must be sent to UDS to execute the transaction (Create operation, see documentation at documentation).
If the payment involves points redemption or the company has a setting to apply a discount to the order, the code parameter must be included.
Example request:
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 '{ \
"code":"string", \
"nonce":"string", \
"cashier":{ \
"externalId":"string", \
"name":"string" \
}, \
"receipt":{ \
"total":100.0, \
"cash":0.0, \
"points":100.0, \
"number":"string", \
"skipLoyaltyTotal ":10.0, \
"unredeemableTotal":100.0 \
} \
}' -X POST "https://api.uds.app/partner/v2/operations"
The following parameters are sent in the Create operation request:
- code – transaction code from the Find customer response, or participant -> phone (phone number in international format, e.g., +7…)
- total – original order total. If external discounts are applied, total should reflect the amount after applying those discounts.
- skipLoyaltyTotal – the amount on which discounts or points accrual should not apply. If the order contains products that should not participate in the UDS system (i.e., discounts do not apply to these items), their total should be passed here.
- unredeemableTotal – the amount on which points cannot be redeemed; the maximum redeemable points will be calculated based on this value.
- points – number of points the customer wants to redeem.
- cash – amount paid with cash/card or combined payment.
- externalId and name – cashier’s ID and name who processed the payment. externalId can only contain digits and Latin letters. In the POS system, this could be an employee ID or number.
- number – receipt number in the POS system.
- nonce – arbitrary UUID string that can only be used once. Recommended to prevent duplicate operations if the request is repeated.
Notes on total calculation:
- If external discounts exist, then:
total = original order amount − (external discount × original order amount) - If the order contains products that should not participate in UDS, then:
total = original order amount − cost of excluded products - If the order contains products for which points should not accrue or discounts apply, their total should be passed in skipLoyaltyTotal.
- If the order contains products on which points should not be redeemed, their total should be passed in unredeemableTotal.
- To redeem points without accruing points, send the Create operation request with:
skipLoyaltyTotal = cash
After the order is created, the server credits bonus points based on the cash amount paid.
8. If the Create operation transaction returns an error from UDS, an alert should be displayed in the online store administrator console indicating that the UDS transaction for this order did not occur.
Error codes:
Status |
Error Code |
Description |
400 |
badRequest |
A validation error occurred for the form. For example, mismatched types or violation of constraints |
400 |
invalidChecksum |
The receipt total does not match the sum of redeemed points and cash. Should be: `cash = total – points – (total – skipLoyaltyTotal) * discount_rate`
Errors often occur because of external discounts, incorrect rounding. *The discount rate in the formula is considered in decimals (i.e., 10% = 0.1). |
400 |
insufficientFunds |
Attempt to redeem more bonus points than are available on the customer’s balance. Typically occurs due to incorrect rounding — round down only. |
400 |
discountLimitExceed |
Attempt to redeem more bonus points than allowed by marketing. The company may set a maximum percentage of the receipt that can be paid with points. In the UDS Business settings – Loyalty program you can view the permissible percentage under “How much of the receipt can be paid with points?” |
403 |
companyIsInactive |
The company is inactive or the company ID/API Key is incorrect |
404 |
notFound |
The requested object, API method or path doesn’t exist. This often happens for an incorrectly entered customer code or if the code’s lifetime expired. Also happens when searching by phone number if that number isn’t registered in the system or no prior transactions exist for it in the company. You should input a new 6-digit customer code from the UDS App. Check the API method, URL, and object existence (this may be customer ID, product ID or transaction). In case of POST request the error may occur if the header `Content-Type: application/json` is missing. |
401 |
unauthorized |
API Key or Company ID are incorrect |
403 |
forbidden |
Access denied, given authentication token is not set or has insufficient permissions |
9. Implement the ability to cancel a payment. That is, when an order is canceled in the online store, the corresponding transaction in UDS must also be canceled.
Request:
https://api.uds.app/partner/v2/operations/{id}/refund
where id is the UDS transaction ID returned in the response after a successful transaction.
To perform a partial refund, include the partialAmount parameter in the request, specifying the amount to be refunded.
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 '{ \
"partialAmount":100.0 \
}' -X POST "https://api.uds.app/partner/v2/operations/<id>/refund"
Required data to store on the integration add-on side:
- After receiving confirmation from UDS that the payment was successful, save the transaction ID and link it to the order to allow for refunds.
10. Provide the ability to print a voucher that allows customers to earn bonus points.
If the order did not include a customer code or phone number (i.e., the order did not participate in the UDS bonus program and no operation information was sent to UDS), a voucher can be generated for the customer. This method allows displaying or printing a voucher code (QR code). When scanned in the UDS App, the customer can receive points for the purchase. Voucher validity: 3 hours.
For more details about the voucher, see the documentation.