In the “customer find” request of the Partner API v2 include the parameter `exchangeCode=true`. Then in the response the field `code` will contain a long-lived code valid for 24 hours. Note: the long code is generated only for the customer code in the app. For a certificate code, order code, wallet card – the original code value is returned without lengthening the lifetime.

• Why is the field `code` empty in the customer search response?

The `code` field is returned only if you searched the customer by the customer code from the UDS App, certificate code, order code or wallet card, and you passed `exchangeCode=true`.

• Can I obtain the customer code via API?

No — the customer code can only be obtained via the UDS App.

• What is the difference between payment via virtual wallet card vs customer code from app?

Unlike the code in the app, the virtual card’s QR code is valid without a time limit but only for the company in which the virtual card was issued. Otherwise the processing (retrieving customer info, performing the transaction) is the same.

• How to scan the virtual card code with a 2D scanner?

The QR code for the virtual card contains a link like `https://wallet.uds.app/add-wallet/{company_id}?ref={card_code}`. You must extract the `ref` parameter and use it to search the customer and perform the transaction in the Partner API. Example processing:

 /^(?:https?:\/\/)?(?:www\.)?wallet.+\?(?:.+&)?ref=(\d+)/gm
Pattern WALLET_REF_URL_PATTERN = Pattern.compile(
"^(?:https?://)?(?:www\\.)?wallet.+\\?(?:.+&)?ref=(\\d+)")

• Why is the field `phone` empty when searching for a customer?

The `phone` field may be empty if the customer did not link a phone number in their UDS account or did not allow providing their number to the company.

• How can I get test access to the API?

Contact support@uds.app to get a test license.

• Where can I find the API Key and company ID?

You can copy the company ID and API Key from the Settings in UDS Business in the Integration section.

• Can I use one API Key and company ID on multiple cash registers?

Yes. Each company has only one integration data in UDS, so you can specify the same API Key and company ID for all cash registers. Identification by cash register / branch / employee is done by passing parameters in the `cashier` field.

• Can I change the percentage of bonus points that are awarded on purchase?

No. The accrual of bonus points depends on the `cash` parameter and the company’s bonus settings. To limit accrual, you can pass the parameter `skipLoyaltyTotal` — the amount of the receipt on which bonuses should not be accrued.

• Can bonus points be redeemed by phone number or by customer UID?

For phone number redemption: yes, but only if the company has the respective setting active (enabled via support team). By customer UID: no — you can only accrue points, you cannot redeem them by UID.

• Can the bonus redemption percentage differ among customers?

Yes — depending on the company’s bonus settings and the customer’s status, the percentage of points that can be redeemed may differ.

• How to determine the maximum amount of redeemable points?

For simplifying the logic of calculating the maximum redeemable points in Partner API v2, when making a “customer find” request include the parameter `total`, equal to the amount of the receipt after subtracting external discounts and optionally the amount of items that should not participate in point redemption.

Then in the response under object `purchase->maxPoints` you’ll get the maximum allowable number of points that can be applied to that receipt (depends on `total`). This solution will also be compatible when redemption by phone number is enabled — `maxPoints` will also include available points.

Also, the amount of permissible points can be obtained by sending a separate request to the “calculate transaction parameters” endpoint.

• What is an external employee identifier?

To identify the employee who processed a payment at the cash register via UDS, you must send an individual employee number — their identifier. This identifier can be set in UDS Business for each employee in the corresponding field “external identifier”.

• What does a 400 response mean?

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` In the case of bonus accrual, discount rate is 0 and formula simplifies to `cash = total – points`. E.g., total = 100, points = 50, then cash = 50. In the case of UDS discount by phone number or UID redemption is unavailable, discount rate = 0: formula simplifies to `cash = total – points`. E.g., total = 100, cash = 100, points = 0 (by UID cannot redeem points, by phone number only under certain settings). In the case of a UDS discount and no promotional goods, skipLoyaltyTotal = 0: formula becomes `cash = total – points – total * discount_rate`. Example: total = 100, points = 40, cash = 50 (for a discount rate of 10 %) In the case of a UDS discount and skipLoyaltyTotal not zero: `cash = total – points – (total – skipLoyaltyTotal) * discount_rate`. Example: total = 100, skipLoyaltyTotal = 20, points = 40, cash = 52 (for discount rate = 10 %) 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

• What TLS protocol version is supported?

The minimum TLS version supported is 1.1.

• Is HTTP protocol supported?

No — requests must use HTTPS.

• Is webhook support available?

Yes — Webhooks are sent when a new customer joins the company, when a transaction is made, and when an order is created.

• How to configure the webhook?

Webhook is configured in UDS Business under Settings → Integration. For notifications specify your server’s address where the webhook will be sent.

• Why are multiple identical webhooks received?

A webhook is duplicated if, for some reason, it was not delivered or didn’t receive a 200 OK response within 5 seconds.

• Can the same event be delivered to multiple addresses?

No — a webhook is sent to only one address.

• Are there example requests in Partner API?

Yes — example requests are available here.

• How to restrict bonus accrual or redemption on particular goods?

To restrict bonus redemption on goods, in the “calculate discount” request (Endpoint `/operations/calc`) or in the “customer find” request you can pass the parameter `unredeemableTotal` — the amount of goods for which bonus redemption is prohibited. Then the `purchase->maxPoints` value in the response will reflect a reduced value accounting for such goods.

To restrict bonus accrual, in the “create transaction” request (Endpoint `/operation`) pass the parameter `skipLoyaltyTotal` — the amount of goods for which bonus accrual should not occur.

If you’re using the outdated Partner API v1, then bonus redemption restrictions must be handled entirely on the integrator’s side. To restrict accrual, subtract the goods from the receipt amount on the integrator side and do not send them to UDS, i.e., send only the sum of goods eligible for bonus accrual to UDS.

• How to tell if a certificate code rather than an app code was applied?

When doing the “customer find” request you can tell if a certificate code was entered — in the response the `type` parameter will indicate the type of entered code: `"PURCHASE"`, `"BONUS_ITEMS_PURCHASE"`, `"GOODS_ORDER_COMPLETE"`, `"CERTIFICATE"`.

• How to find the amount of bonus points to be awarded for a purchase?

Use the “calc” method and specify the same parameters that will be sent when performing the transaction. In the response the number of bonus points will appear in the object `purchase -> cashBack`.

You can also calculate it yourself using the formula: bonus_points = (cash payment amount (cash) – amount of goods not eligible for bonus accrual (skipLoyaltyTotal)) * bonus accrual percentage (cashBackRate). If the result is less than or equal to 0, then no points will be accrued for this purchase.

• Can I get the list of orders in the company?

No — currently you can only get information for an order by its identifier.

• Is order status change supported via API?

No — at the moment order status can only be changed in UDS Business.

• Can I cancel an order via API?

No — currently order can be cancelled only in UDS Business.

Was this article helpful?