Nayax, MoMa and Operator: card payments and revenue manual

Reviewed against the local source and official Nayax documentation on 7 September 2026 (UTC). This describes the reviewed software implementation and its unfinished integration points; available functions depend on the running app and backend release. No live reader, merchant account, card charge, refund or bank payout was exercised.

Release scope: the backend release accompanying this manual includes the stricter event validation described below. This validates the existing normalized ingestion contract; it does not add or activate a native Nayax transaction feed. Confirm the running backend release before relying on its rejection behavior.

MoMa displays Nayax account data. It does not send money to Operator. Nayax Core is the web management system and MoMa is its mobile companion; they work with the same account data. Operator is a separate application and needs an approved transaction integration to display those card sales. Nayax MoMa overview

1. Where money goes, and where data goes

Nayax describes the machine-to-reader connection and the reader-to-Core connection as separate links. A reader can have cellular connectivity while its vending-controller communication is broken. “Online” in MoMa is therefore insufficient evidence that a card selection can vend. Nayax system overview, Nayax vending integration

The local code does not retrieve or verify your bank details from Nayax. Any local merchantAccountId or settlement-account label is configured attribution metadata, not proof that Nayax has changed the merchant receiving the money.

2. What is available for each machine family

Spark is a separate remote-payment API, not an automatic hardware compatibility layer. Its local implementation status is described in section 7.

3. Commission the merchant account and bind the actual reader

1. In Nayax Core, confirm that the physical reader belongs to the intended operator/merchant and that the account's financial onboarding is complete. Verify access in MoMa with that account. Missing machine access should be resolved with the Nayax account administrator.
2. For a used or transferred reader, complete Nayax's process for the account's region. For example, the US/Canada process uses both parties' Operator/Core IDs, reader serials and transfer approval. A Kiosk-X ownership change or reader binding does not perform that transfer. Nayax US/Canada device transfer guide
3. Record the machine's Kiosk-X machineNo, cabinet serial, controller model, installed APK/version, Nayax Device Number, printed hardware serial, Nayax Core Machine ID and merchant/operator name in the commissioning record. Keep the different identifiers in separate fields.
4. In Flutter Operator, open Machines → the machine → Nayax card reader → Bind/Replace. Enter the actual Device Number and, where available, its hardware serial. Read the saved binding back. The short Nayax Core Machine ID is not the Device Number to enter here.
5. Verify that exactly one local machine claims the reader. The backend rejects conflicting bindings and matches numeric Device Numbers without treating leading zeroes as a different reader; retain the printed identifier in your records.
6. Check the local owner and merchant attribution with an administrator. The binding API supports additional merchant/Core actor metadata and flags including settlesToOperator, nayaxWebhookExpected and cardMode; the current Flutter binding form exposes only the reader ID/serial/model subset. Do not assume the app has verified these advanced settings.

Binding records a local mapping. It does not provision a Nayax reader, move the Core device, change the bank account, test MDB, enable a feed, or prove that a payment settled. A provisional registration ID must be replaced with the real reader identity.

Use a controller- and firmware-specific commissioning profile supplied for the installed equipment. Do not copy an MDB level, idle mode or reader profile from another machine family merely because both have Nayax readers.

4. How card transactions can reach Operator

Official Core transaction delivery

Nayax documents transaction delivery through Amazon SQS. The account needs the Transaction Dispatcher and Transactions Report Subscriber roles. In Core: Administration → Operator → select the operator → Transactions Report. Enable Amazon SQS, supply the queue configuration, validate it, choose the required payment methods/event types and columns, then save. Arrange this with the Nayax account administrator/integration team. Keep queue credentials on the server. Official Core transaction delivery procedure

A Core SQS consumer and native-event-to-Kiosk-X mapping have not been found in this backend. This is an integration gap, not a MoMa setting. The native SQS documentation contains fields such as TransactionId, PaymentMethodId, MachineId, MachineTime, Void and nested Data; that is not the same payload as the local HTTP endpoint. The actual selected report columns and sample events must be reviewed before mapping them. Nayax SQS setup and payload guide

If Nayax provides another approved delivery product for your account, its exact authentication, schema and lifecycle also need a verified adapter. Pasting the local URL into MoMa is not an established setup procedure.

Existing backend ingestion contract: integrator reference

POST /api/v1/payments/nayax/webhook accepts a Kiosk-X normalized settlement event, authenticated with X-Nayax-Signature: hexadecimal HMAC-SHA256 over the exact request bytes using KIOSKX_NAYAX_WEBHOOK_SECRET. Missing/default secrets are refused. This is the local contract; it is not a claim that native Core SQS or native Spark callbacks use this signature.

The adapter must explicitly distinguish authorization, decline, capture, cancellation and refund. The accompanying backend release rejects explicit authorization, declined, unknown or malformed event types before modifying orders, credits, stock or vend queues. Conflicting event aliases and unsuccessful/pending status fields also return 400. A sale's supplied settlementStatus, transactionStatus, status or verdict must be settled or captured; an adjustment's supplied status must identify its completed result, such as refunded or voided. Fields are checked case-insensitively. A supplied success/approval flag must be true; a sale's supplied capture flag must also be true. An original sale's capture flag does not establish that a refund or void completed. Native status objects require normalization.

The legacy payload without an event discriminator remains accepted as a settlement-only contract. Its optional status fields are still validated. It is not suitable for raw authorization, decline, free-vend or heartbeat messages. Machine heartbeats use their own existing device endpoints. The earlier backend behavior could turn unknown events into settled sales; the accompanying backend release adds the new rejection gate. The source adapter must validate lifecycle states independently in either case.

Legacy completed adjustments may omit status. For compatibility, a signed normalized refund, void, chargeback, reversal or cancellation event without status is an assertion that the adjustment completed. The backend does not independently verify that assertion with Nayax. The adapter must withhold pending/requested adjustments until completion is confirmed and should send the corresponding completed status explicitly. Any supplied pending, failed or conflicting status is rejected. Do not send a raw provider adjustment event merely because its type name matches.

Additional integration requirements before enabling a production feed:

• Preserve the provider's event timestamp and raw event reference in a durable integration ledger. A newly created webhook order currently uses ingestion time for buyTime; a delayed batch cannot be assumed to land in the original transaction day.
• Use transaction IDs for replay protection. The endpoint has a raw-body hash fallback when the ID is absent, but serialization changes can change that hash. It is not a substitute for stable source identities.
• Resolve identity conflicts, mismatched currency/amount and missing selection into an explicit review queue. A successful HTTP acknowledgement alone is not proof of the correct order, delivery or bank payout.
• Retain failed events with their error and retry state. Refunds arriving before their original sale currently return 404 and need ordered replay/reconciliation.
• Keep partial refunds separate until partial-amount accounting is implemented. The current recognized refund/void path adjusts the entire original order; it must not be used to represent a partial refund as a full refund.
• Separate historical reconciliation from live vending. Do not bulk replay historical sales into this live endpoint: eligible ZHZN events can queue a physical vend. A dedicated reconciliation-only import mode is needed before backfilling.

There is no automatic transaction pull from a MoMa login, no verified native SQS bridge and no native bank-statement importer in this source. Deployment configuration was not inspected, so an external connector operated elsewhere remains unverified.

5. Read the different payment and delivery states correctly

For a normal local MDB vend, reconcile approval, physical delivery and final capture as separate evidence. For a capture-before-delivery flow, a vend failure creates an amount owed to the customer. Do not initiate a fresh paid sale to repair the original transaction.

6. What users can do in Operator today

The card summary is not grouped by currency and rounds aggregate values to two decimals. Never add mixed-currency records or compare them with a single bank payout. The current report/API also lacks a processor-fee and bank-deposit ledger. Date-filtered revenue endpoints use UTC date boundaries; compare the same timezone and event basis as the Nayax report.

The revenue implementation already removes refunded orders from product-sales revenue. Do not subtract the displayed informational refund total a second time. Fields historically named netUsd or revenueUsd do not make the figure processor-net proceeds or profit; use the record's actual currency and verify the endpoint's scope.

7. Configured, available and unfinished payment operations

Official Spark supports remote server-to-server payment sessions and documents a two-part authentication process and callbacks. Nayax Spark overview

In this checkout, _auth_headers() still constructs a bearer token and X-Token-Id; its own comment says the real authentication needs replacement. Callback normalization is custom, currency display still assumes a two-decimal dollar amount, and successful callback dispensing uses the MQTT path rather than a universal Reyeah/ZHZN/Vendron adapter. Setting cardMode: spark and nonempty environment variables is therefore insufficient. Complete the published authentication/callback/capture flow, supported currency handling, controller-specific dispatch and provider acceptance before enabling it.

Secrets default to empty in source. No claim is made that the deployed service is configured or unconfigured. Never put provider secrets or a webhook signing secret in the Flutter APK.

8. Daily sales, receipts and refunds

1. Choose one machine, currency and time window. Start with a newly commissioned sale so ingestion time and source event time can be compared directly.
2. In MoMa, open the machine and Last Sales; locate the settled transaction by time, product or last four card digits. Open it and select Generate Receipt, then download the PDF. Retain the Nayax transaction ID, reader identity, amount and currency with the corresponding Operator order. Official MoMa receipt procedure
3. In Operator, confirm the same machine, aisle, order, amount and currency. Check delivery evidence separately. Confirm that a later provider record joined the existing device sale instead of making a duplicate order or consuming stock twice.
4. Compare captured transactions, device-reported pending transactions, failed delivery, voids/refunds and missing records as separate groups. Investigate a settled record without delivery and a delivered record without settlement.
5. To return a Nayax card payment, locate the settled transaction in MoMa/Core and use its refund request/approval workflow. Account permissions govern both submission and approval; pending transactions are not eligible for the documented settled-transaction refund workflow. “External refund” in MoMa records a return made elsewhere, so it is not a shortcut for issuing a new refund. MoMa refund prerequisites and troubleshooting
6. Verify provider confirmation. A correctly connected refund event can adjust the original Operator order. Otherwise, an authorized administrator can record proof through POST /api/v1/orders/{orderNumber}/refund with external: true, externalReference and a reason. The Flutter form does not currently expose those proof fields. Do not mark a refund complete just to clear the queue.
7. For cash, reconcile the physical collection and change/refund record. For Stripe QR/Scan & Pay, reconcile the Stripe transaction and payout. Neither is expected in the Nayax cashless settlement summary.

9. Reconcile the bank payout

Use the financial reports for the region and agreement attached to the merchant account. Nayax's North American reimbursement-report instructions use the separate Financial Reports portal: register/verify the Nayax ID and registered email, choose the report period and request the report. Confirm the correct regional process with your account administrator. Official reimbursement report procedure

Nayax's UK/Ireland statement guide distinguishes gross amount, reimbursed and non-reimbursed transactions, processing/service fees, applicable tax on fees, adjustments and total to transfer. Use the actual statement's definitions and sign conventions; this regional example is not a universal payout schedule. UK/Ireland payout statement guide

For each statement, record:

Illustration only: if a statement starts with 100.00 captured sales and separately deducts 10.00 refunds and 4.00 total fees, the transfer is 86.00 before any other adjustments. A local sales total already excluding the refunded orders would be 90.00; subtracting the same refund again would understate revenue. Actual rates, timing, reserves and payout currency come from your own agreement and statement.

10. Acceptance evidence and remaining work

Complete one signed commissioning record per physical controller/APK/reader configuration, then repeat after material firmware, payment-profile or adapter changes:

• Machine/reader/merchant identity and bank-account ownership confirmed through Nayax records.
• Display stable and controller health verified; cabinet identity established before installation.
• Product/price/stock readback matches the physical slot and charged currency.
• One successful customer flow: one authorization/capture as applicable, one delivered item, one stock change, one Operator order and a matching Nayax receipt.
• Decline, cancellation and timeout cause no unearned delivery or false sale; captured-but-undelivered payment enters the refund workflow.
• Duplicate and delayed events do not duplicate a vend, sale or stock change; restart/reconnect preserves reconciliation.
• Full refund is verified at the provider and reflected once in Operator; partial-refund support remains separately tracked.
• The resulting Nayax statement reconciles to the merchant bank credit.

Offline software evidence: the focused suites test_nayax_event_validation.py, test_nayax_webhook_hardening.py, test_nayax_steps_do_not_assert_core_state.py and test_nayax_spark.py passed 82 tests with 26 deprecation warnings. The guard recorded zero network attempts. The new cases check that rejected events leave orders, pending card sessions, transaction IDs, stock, credits and command queues unchanged, while valid captures and adjustments still work. Spark requests were mocked and vending checks used only an in-process queue; this does not verify native Nayax authentication, a live feed, physical dispensing or payout. Detailed test logs are retained with the release validation record. See machine setup and release status for available installers and their limits.

Before claiming complete in-app Nayax operation, deliver the native event adapter, preserve source-time reconciliation, add safe historical imports and partial-refund handling, verify per-currency summaries, expose external-refund proof where appropriate, and commission each supported controller. Silkron/Vendron and the unidentified DFY/VC EL machine require their own identity and integration work.