Debug a Nayax reader on a ZHZN vending machine

Field guide · reviewed 10 September 2026. Start at the first step that fails. A reader can be online in Nayax Core while the cabinet cannot start a card sale. Moving a reader does not prove the old machine name caused the failure.

For first installation or a reader transfer, follow New machine and Nayax setup. This guide covers the ZHZN Kiosk-X APK with an MDB bridge. The historical Reyeah activation guide describes a different controller; its MDB profile is not a ZHZN default.

Visual walkthroughs: where to click

Prepare the support call

Start here: choose the symptom

The chain to test is Buy Now → checkout → Card selection → local APK sale request → MDB reader approval → vend controller → delivery result → Nayax settlement. A green badge at one stage does not prove later stages.

Step 1 — Identify both cabinets and save a baseline

1. Open Operator X and select the affected machine. Record its full machine ID, site name, last heartbeat and installed APK version. Repeat for one working machine with the same actual controller/bridge family.
2. Read the physical Nayax Device Number and find that exact number in Nayax Core. Record the separate Core Machine ID, machine reference and actor/operator. Keep leading zeros in device numbers.
3. Compare the physical reader with Kiosk-X's terminalId and deviceSerial. Both should contain that reader's Device Number. The number in a Core page URL is its internal Machine ID, not the terminal number to bind.
4. Include offline and returned machines in the operator's inventory search. A former machine must not retain the moved reader's real number in either matching field. Follow the transfer steps in the setup guide if it does.
5. Save the current features, agent configuration, identity, device credential state, reader state and a fresh timestamped screen. Save only relevant diagnostics; exclude API keys, service PINs and cardholder information from tickets.

Pass: you can identify the cabinet, Android installation and reader independently, with no duplicate reader alias. The same site name or last four characters is insufficient. The two cabinets investigated in September shared an ID suffix and ran different installed APK versions despite an assumption that they used the same APK.

Comparison worksheet

Step 2 — Establish whether checkout actually opens

1. Confirm a stocked, available product has a valid price and currency. Leave service/test mode and any unfinished checkout through the normal UI.
2. On the physical screen, select the product and press Buy Now once. Note the exact local time and timezone. Record whether the screen stays unchanged, opens an empty payment panel, or shows other payment methods.
3. Inspect a newly captured screen and the corresponding screen/checkout events. A command marked queued or delivered is not a fresh screen. A stale heartbeat is not proof the app received a recent change.
4. If no checkout opens at all, investigate the storefront, its network requests, catalog/stock eligibility and any board/checkout refusal. Do not start by changing the Nayax actor or replacing MDB wiring: no reader request may have been made.
5. If checkout opens but Card is missing, continue to Step 3. If all payment options are missing, retain that distinction in the ticket.

Pass: a new checkout exists for the selected product and amount. Record its order/session identifier if one is created.

Step 3 — Check the two separate card controls

Open this cabinet's settings/diagnostics in Operator X. UI labels vary by release; if a field is not exposed, an authorized platform technician uses the API appendix below. Do not assume the service menu includes every cloud feature switch.

1. Check agent-config.mdbEnabled=true. This enables hardware integration/discovery.
2. Separately check features.cardTapStorefront=true. This opts the ZHZN hosted storefront into showing Card. MDB enabled alone does not enable the Card option.
3. Keep cardTapForceTile=false. A diagnostic override can make a button appear despite failed readiness; that is not a repair.
4. Check fresh reader readiness, board initialization, any explicit card-visibility refusal and an existing active checkout. An enabled feature cannot overcome every hardware or checkout block.
5. If only the storefront flag is confirmed wrong, save its before value, change that field, and perform an independent readback. Start a fresh checkout after the app receives the change.

Pass: Card is visible and selectable with a real ready reader and without a force override. htmlStorefront is not the ZHZN card switch; it selects a Reyeah storefront behavior.

Step 4 — Check the app, controller and MDB connection

1. On supported ZHZN APKs, open the service menu by tapping the top-left corner seven times within five seconds, then enter the authorized cabinet PIN. Use Board codes / 主板代码 for diagnostics or Factory test / 工厂测试 under the approved service procedure. See Android operation. Older versions may expose different screens; use device telemetry when needed.
2. Inspect fresh board initialization and the detected module, vend UART and baud. Compare them with the saved cloud configuration. A working auto-detected module can conceal an incorrect saved fallback.
3. Inspect MDB bridge initialization, selected UART, detected cashless address and ready/state. An earlier successful discovery is insufficient if the current app is disconnected.
4. Select Card and correlate that checkout with the APK's local card-sale request, requested amount and MDB response. If the UI records Card selection but no local request arrives, investigate storefront-to-agent communication. If a request arrives but no reader response follows, investigate the bridge/profile/harness.
5. For the two observed SH/CSM cabinets, the working links were vend /dev/ttyS4 at 9600 and MDB /dev/ttyS1, with cashless address 16 (0x10). These are evidence for matching hardware, not universal ports to force onto every ZHZN model.
6. Have a qualified technician inspect/reseat the correct MDB harness and bridge with cabinet power isolated according to the manufacturer's procedure. A powered screen only proves some power is present. Do not hot-swap cables or improvise power adapters.
7. Correct only a confirmed mismatch. Then perform the complete-cabinet restart in Step 8 and collect new initialization evidence.

Pass: the reader displays the selected price and currency when Card is chosen. If the price is wrong, stop before tapping and compare the catalog amount, sale request, currency and reader scaling/profile.

Nayax screen codes and profiles

Nayax documents V00 as missing MDB signal, V01 as an inactive connection awaiting initialization, and V02 as a reader disabled by the controller. For V02, check door/service state and outstanding credit as well as faults. These distinctions help choose the next check; they do not prove a particular component is defective. Nayax's official code guide.

The observed working ZHZN bridge used MDB Level 3 Always Idle / Product transaction start. The historical Reyeah procedure and generic Nayax flag recipes target other conditions. Before changing an MDB level, Ignore flag or start mode, record the current profile and confirm compatibility with the actual controller/bridge through its manufacturer or Nayax. Apply the intended change through Core, then verify that the device received it; a queued update or unchanged Online badge does not establish application. Nayax MDB attribute reference.

Step 5 — Price appears, but payment fails

1. Record the reader's exact message/code and the attempted amount/time. Do not infer the meaning of an undocumented numeric transaction status.
2. In Nayax Core's transaction report, filter the exact reader/machine and the correct time interval. Account for the report timezone. Determine whether there is no attempt, a decline, an authorization or a settlement.
3. If no transaction exists, check the reader's connectivity and activation, plus whether the card was actually read. Reader cellular connectivity and Android internet connectivity are separate paths.
4. If there is a decline, use the processor's stated reason and the operator's established support procedure. Repeated paid attempts are not a useful cable test.
5. If approved, follow the same transaction into the vend result in Step 6. A temporary authorization does not establish final settlement.

Pass: an identified transaction proceeds to an approved vend attempt, or its exact failure has been isolated and corrected before another supervised test.

Step 6 — Payment approved, product missing

1. Pause further paid tests for the affected selection. Record the order ID, Nayax transaction, amount, aisle and time.
2. Inspect the vend command, board acknowledgment, motor result, product-fall evidence and physical stock. A motor spin or a generic shipped label does not prove the customer received a product.
3. Inspect the APK's success/failure report to the reader and the final Nayax transaction result. Resolve the original charge using the established operator/Nayax reversal or refund process after verifying its actual state; do not issue a second action blindly.
4. Repair the physical dispense, selection mapping or result-reporting fault. Do not increase vend-result timeouts merely to conceal missing completion reports.
5. Complete an attended delivery and settlement check before reopening that selection.

Pass: the product is physically received, the board reports the appropriate result, inventory changes correctly, and the financial result matches what happened.

Step 7 — Reconcile a successful vend

Compare the same full machine ID/reader, order ID, amount, currency, selection and timestamp with the Nayax transaction report. Preserve the Nayax transaction ID and final settled amount in the private acceptance record.

If Nayax confirms settlement but Kiosk-X remains pending, investigate webhook delivery, attribution and both reader aliases. Keep the discrepancy explicit. Do not edit old orders to manufacture a match. See Payments and Nayax.

Step 8 — Restart and prove recovery

1. Wait until the cabinet has no active payment, vend or update. Preserve the before/after settings and relevant order evidence.
2. Use the manufacturer's normal complete cabinet power procedure so Android, the controller, MDB bridge and reader initialize together. A reader restart, APK relaunch or Android-only restart is not evidence of a complete cabinet power cycle.
3. Confirm the APK automatically returns with the same full machine ID. Check a new heartbeat, successful board initialization and fresh MDB ready/enabled state.
4. Select a stocked product, press Buy Now and select Card. Confirm the reader's exact price and currency before presenting a card.
5. Conduct one supervised purchase. Observe the physical product, verify stock changed once, and match the order with its Nayax settled transaction. Record any pending settlement separately if final settlement is not yet available.
6. Record the operator/technician, time and each result. Reopen only the functions that passed. If a configuration change worsens behavior, restore that specific recorded value and keep the failed payment path unavailable while diagnosing.

Worked RCA: the September 2026 ZHZN case

The reported symptom was no usable Card option after a reader had been tried on a Reyeah machine and returned to a ZHZN cabinet. The reader and board had working communication evidence. The confirmed immediate blocker was cardTapStorefront=false; enabling it was followed by real Card selection, reader approval and a board-success report. A matching $8 Nayax settlement was independently verified.

Two separate defects were also corrected: a saved controller fallback disagreed with the detected SH controller, and the returned machine retained the moved reader in deviceSerial. That stale alias could confuse settlement attribution because both binding fields are matched. It did not explain the disabled Card option. The APK versions were also different, so “same APK” was not an established fact.

The full cabinet power cycle, the price physically displayed on the reader and a person's observation of the drop were not directly verified in that investigation. This distinction is why the acceptance checklist requires both remote records and on-site observations. Internal asset numbers, transaction identifiers and screenshots stay in the private incident record.

Authorized technician API appendix

Use the live API reference and an authorized operator/platform session. Substitute the full machine ID; never paste another cabinet's ID. Access is role dependent, and raw telemetry requires platform administration. A 401/403 is an access problem, not proof the hardware is offline.

For the confirmed missing-option fault, the minimal features body was:

{"cardTapStorefront": true}

Read back the value independently. This change is appropriate only after confirming the reader assignment and usable hardware. To disable that option again, send false for the same field. Preserve existing unrelated settings and do not send a wholesale copy of the working machine's configuration.

Escalation packet

Copy this into the private service ticket. Contact the platform team for checkout/configuration, the cabinet/bridge supplier for hardware communication or delivery, and Nayax/the registered actor for reader activation, profiles and processor results.

Date/time/timezone and technician:
Full Kiosk-X machine ID / site:
Cabinet model / board / bridge:
Installed APK version:
Physical Nayax Device Number / Core Machine ID / actor:
Exact shopper symptom and reader message:
Last fresh heartbeat and screen time:
Configured vs detected module / vend port / baud / MDB port:
MDB ready/state/address and board init/fault:
Card flags before → after, with independent readback:
Old/returned records checked for both reader aliases:
Order ID / Nayax transaction ID / amount / currency / result:
Complete cabinet restart observed? When?
Reader price observed? Physical product received? Stock correct?
Changes tried, outcomes, rollback and remaining failed step: