Cart Integrity: What the Server Checks on a Storefront Cart
A CP Commerce (Cross Platform Commerce) storefront works out a cart’s prices and totals in the browser.
When a website has Cart Security switched on, the server
checks those numbers on every cart save, at checkout and before payment, and answers HTTP 400 with a
CLIENT_CART_… or CLIENT_PGW_… code when one does not hold. This page is for the developer who builds
on the cart routes or supports a storefront that received one of those codes.
Read a refusal
- Take
codefrom the body of the HTTP 400.messageis written for a log or for the shopper, depending on the check. - Find the code in the table below: it names the check and the setting that decides whether the check refuses or only records.
- Reload the cart from the server before you retry. The server’s copy is the one the next check is made against.
A payment reference asked for RM 4,298.00 on a cart that owes RM 4,299.00 is answered:
{
"code": "CLIENT_PGW_AMOUNT_MISMATCH",
"data": null,
"message": "cart 6f1c2a9e-3b7d-4e55-9a10-2c8d5e7f4b21 UNDERPAID: requested 4298.00, payable=4299.00 (goods=4299.00, credits=0.00, creditLines=0, tolerance=0.01)"
}Codes and the setting behind each
Every check below runs only while enable is "true" in the website’s settings block
(The settings block); the one exception is noted in the points row. The texts a shopper is shown are listed on
Cart Security.
| Code | Raised when | Refuses when |
|---|---|---|
CLIENT_CART_LINE_AMOUNT_INCONSISTENT | A product line’s amounts do not agree with each other | Always, while enabled |
CLIENT_CART_LINE_UNIT_PRICE_CHANGED | A line already in the cart changed its standard unit price | Always, while enabled; a change to the store’s current price is accepted when price_verify_mode is log or enforce |
CLIENT_CART_LINE_PRICE_NOT_VERIFIED | A line added by this save is found at a price that is not the store’s for the item; message names the item | price_verify_mode is enforce |
CLIENT_CART_LINE_DISCOUNT_NOT_VERIFIED | A line claims more discount than the store’s setup gives | discount_verify_mode is enforce |
CLIENT_CART_CASH_VOUCHER_NOT_VERIFIED | A cash voucher credit does not match the shopper’s vouchers or the cart | discount_verify_mode is enforce |
CLIENT_CART_POINT_CONVERSION_NOT_VERIFIED | A points credit does not match the website’s rates or the member’s balance | discount_verify_mode is enforce. The checkout’s own points test raises the same code with Cart Security on or off |
CLIENT_PGW_AMOUNT_MISMATCH | The amount requested differs from what the saved cart owes by more than the tolerance | pgw_amount_verify_mode is ENFORCE |
CLIENT_PGW_CURRENCY_MISMATCH | The currency requested is not the cart’s | pgw_amount_verify_mode is ENFORCE |
CLIENT_PGW_CART_NOT_FOUND | No open cart has that identifier, for example because it is already an order | pgw_amount_verify_mode is ENFORCE |
CLIENT_CART_LINE_INTEGRITY_HASH_MISMATCH, CLIENT_CART_LINE_INTEGRITY_HASH_MISSING and
CLIENT_CART_LINE_PRICE_DRIFT_DETECTED are still defined, and the storefront still holds messages for
them, but the current server does not raise them: checkout checks a line again instead of refusing it.
The routes that run the checks
flowchart TD
S[Storefront] -->|cart save| SAVE[Save checks]
SAVE -->|lines signed| DB[(Saved cart)]
S -->|convert-to-sales-order| CO[Checkout checks]
S -->|generate-payment-reference| PAY[Payment amount check]
PAY -->|reference issued| GW[Payment gateway]
GW -->|payment confirmation| CB[Cart read again]
CO --> SO[Sales order]
CB --> SO
CO -.->|a check set to log doubted it| REV[Review mark on the order]
CB -.->|a check set to log doubted it| REV
All paths start /core2/tnt/dm/.
| Step | Routes |
|---|---|
| Cart save | POST erp/gen-doc/internal-shopping-carts/login-ep, PUT erp/gen-doc/internal-shopping-carts/login-entity-ep, and the internal shopping cart controller’s own create and update |
| Checkout | POST cp-commerce/internal-shopping-carts/convert-to-sales-order/login-entity-ep, and the purchase-by-points route |
| Payment request | The five cp-commerce/internal-shopping-carts/generate-payment-reference… routes |
| Payment confirmation | POST cp-commerce/internal-shopping-carts/direct-url-confirmation/public/{tenantCode} and its indirect-url-confirmation twin |
On a cart save
The first refusal ends the save. Two checks look at the whole request first, three run line by line, and one closes:
- Price lock, whole request. For a product line the server has already signed, the standard amount
divided by the quantity may not move by more than 0.01. Changing the quantity keeps that figure; changing the
price does not. With
price_verify_modeon, a move to the store’s current price is let through first. - Item price, whole request. A line the save adds for an ordinary or grouped item is compared with the price the website’s pricing scheme gives that item, to within 0.01.
- Discount, each line in turn. The line’s discount is compared with what the server recomputes from the website’s default discount price book, the voucher the line names and the made-to-order options. An update is judged against the cart as it will be stored, so rules that span lines see every line.
- Amounts, the same line. On an ordinary line
amount_netmust equalamount_stdlessamount_discount, andamount_txnmust equalamount_netplus the two tax amounts, each within a rounding tolerance; a stated tax rate must give the tax amount. - Signature, the same line. The server derives the line’s unit prices from its amounts and quantity,
then signs the line and stores the token in
line_integrity_token. - Cash vouchers, to close. Each credit line that names a settlement voucher is compared with the vouchers the shopper holds, its face value and the cart’s open balance.
Because steps 3 to 5 run per line, an amount refusal on one line can come before a discount refusal on the next. The token is the server’s: you do not compute it, and you send lines back as the server returned them.
At checkout
- The price lock runs against the stored cart.
- Each product line’s discount is compared as on a save.
- A line whose token still matches its values is accepted. Any other line has its amounts checked, against the stored line when there is one, and is signed again. Steps 2 and 3 run line by line.
- Points credits are compared with the website’s rates and the member’s card; cash vouchers as on a save.
- The whole cart is reviewed once more, and the reasons found by checks set to
logare written on the sales order (Flagged orders).
Checkout re-checks rather than refuses a changed line because an honest checkout differs from the last save: discounts applied in the order summary, a recalculated shipping line and carts older than the switch all arrive unsigned.
At payment
The amount you request must be the amount the server works out from the saved cart, so save the cart before you ask for a payment reference.
goods = amount_txn of each product line (PNS) that is not DELETED, added one at a time,
the running total rounded to two decimals after each
balance = goods, then amount_txn of each credit line (STL_MTHD) that is not DELETED
subtracted one at a time, rounded to two decimals after each
payable = max(0, balance)The rounding is the storefront’s, step for step, so do the sums in the same order. The tolerance is 0.01
plus 0.01 for each credit line. Points and cash voucher credits are checked first, under discount_verify_mode.
With ENFORCE, a request outside the tolerance is refused and no reference is issued. The amount that
goes to the gateway is the one you sent, now shown to match. With LOG, the
reference is issued and the difference becomes a review reason. When it could read the cart, the server
stamps the payment transaction with what the cart owed (cart_amount_verification: payable, goods, tolerance,
mode, verified_at).
When the gateway confirms the payment, the server reads the cart again:
| What it finds | ENFORCE | LOG |
|---|---|---|
| The goods total grew by more than the tolerance after the amount was stamped | The payment is recorded and the cart is not converted | The order is created and flagged |
| No such growth, and the cart’s stored open balance agrees with the server’s figure | The order is created; its open balance is the stored balance less the payment | The same |
| No such growth, and the stored open balance disagrees with the server’s figure | The order is created; its open balance is the server’s payable less the payment | The order is created; its open balance is still the stored balance less the payment, and the disagreement is logged |
Credits that disappeared between the stamp and the confirmation do not block the order; they fall under the last two rows.
The settings block
The settings are one JSON object, line_integrity_config, in the website record’s properties. The
Cart Security tab writes five of its keys and keeps the rest.
{
"enable": "true",
"pgw_amount_verify_mode": "ENFORCE",
"discount_verify_mode": "log",
"price_verify_mode": "log",
"day_limit": 3
}| Key | What it decides | Missing or not recognised |
|---|---|---|
enable | The text "true" switches Cart Security on; the three modes below then decide which checks refuse, record or stay off | Treated as off: none of the checks runs |
pgw_amount_verify_mode | Whether a payment request outside the tolerance is refused (ENFORCE), let through and recorded (LOG) or not compared (OFF) | Treated as ENFORCE, so a typing mistake does not switch the check off |
discount_verify_mode | Whether a discount, cash voucher or points credit the server finds wrong is refused (enforce), recorded on the order (log) or not compared (off) | Treated as off: the check does not run |
price_verify_mode | The same three values for the price of a newly added line; log or enforce also lets an existing line move to the store’s current price | Treated as off: the check does not run |
discount_tolerance | How far a line’s discount may exceed the server’s figure before it counts as wrong | Defaults to 0.01; a negative number is read as its absolute value |
day_limit | written by the tab’s Tampering window (days) | read by nothing that runs |
Three things the block does not show:
- It is read on every request, so a change applies to the next cart or payment call.
- The server adds a signing key to the block on the first cart request after
enableturns on. Leave it in place when you write the block; write only the keys above. - One website’s block governs the tenant. A cart request names no website. The server reads the
block of one active website that has one, the same one each time, and uses that website’s pricing
scheme and default discount price book for the comparisons. A tenant with several active websites
should keep the block identical on all of them, and keep
discount_verify_modeandprice_verify_modeonlogwhile those websites price differently.
Flagged orders
A check set to log does not refuse. What it doubts is written on the sales order header’s properties
under order_review, at checkout or when the payment is confirmed. For an order paid through the
gateway the reasons are gathered when the payment reference is requested, so they exist only if
pgw_amount_verify_mode was ENFORCE or LOG at that moment:
{
"order_review": {
"status": "PENDING_REVIEW",
"reasons": ["price of Flagship Phone 256GB is 42.99 a unit, but the store's price is 4299.00"],
"checkpoint": "checkout",
"flagged_at": "2026-11-17T10:15:00.482+08:00[Asia/Kuala_Lumpur]"
}
}The server always writes this key itself and removes a value sent in by the browser. checkpoint is
checkout or payment, and flagged_at is the server’s clock as Java prints a zoned date-time, so its
zone suffix depends on the server. A review that failed to run adds the reason the automatic check could
not run.
As of 17 November 2026, no screen in CP Commerce Admin or the storefront shows or lists the mark, and
no BigLedger code reads its status: an order with the mark is posted and fulfilled like any other.
If the store wants flagged orders held, that is for your integration or for a person to do. Read
order_review when you pull the sales order, and route an order that has it to whoever releases web
orders, who compares its prices, discounts and credits with the store’s setup before picking. The
store-side routine is on Cart Security.
What it leaves to you
- Holding a flagged order, as above.
- A payment with no order. The
ENFORCErow in the payment table leaves a recorded payment and an unconverted cart. The server logs it and takes no further step; the store finds it by matching the gateway’s settlement report to the day’s orders, then refunds it or raises the order by hand. - The day limit.
day_limitis still written by the tab and read by nothing that runs; do not build on it.
Server log lines
Support staff with access to the server log can search these prefixes; quote one when you raise a case.
| Prefix | Means |
|---|---|
[line-integrity] checkout re-validating cart line | A checkout line was checked again because it was unsigned or had changed |
[line-integrity][unit-price-changed] | A price change on an existing line: detected, refused, or accepted as the store’s price |
[price-verify][would-reject] | A new line not at the store’s price, in log |
[discount-verify][log-only] | A discount, cash voucher or points credit that enforce would refuse |
[pgw-amount][rejected] · [would-reject] | A payment amount refused in ENFORCE · let through in LOG |
[pgw-amount][underpaid-blocked] | Paid, but the goods grew after the stamp: refund or reconcile |
[pgw-amount][credits-changed] · [open-balance-corrected] | The two reconciliations in the payment table |
[order-review] order … flagged for review | An order was flagged. Other [order-review] lines mean the review itself did not finish |
Related documentation
- Cart Security — the store owner’s setup, the shopper messages and the manual review.
- E-commerce API notes — the three cart controllers.
- Integrate an External System — the rest of the integration surface.