Release notes

Review each Terminal API release for new capabilities, fixes, and integration actions. Service improvements are included in the same release history, with their availability date where it differs from the app release date.

The following checklist covers migration to API v2 and the current response handling.

Migration checklist (v1 → v2)

1

Update the endpoint URLs

Switch the URL prefix from /api/v1/... to /api/v2/....

2

Generate an exchange identifier

Generate a UUID for each new operation. Keep the same Header.ExchangeIdentification when resending that operation.

3

Identify the sales system

Add a Header.SalesSystemInfo block (IntegratorId + at least one SaleSoftware with Type and Status.VersionNumber). Request the new values from your contact within Worldline.

4

Read successful payloads

Read Nexo business payloads from body.data. Read asynchronous acknowledgements and transaction-status responses from the response root.

5

Read error responses

Read errors from body.message; remove any body.code lookup.

6

Handle asynchronous responses

Handle 202 Accepted for new async work and 200 OK for an existing exchange. Read transactionId, status, and requestId from the acknowledgement root; consume the webhook Nexo payload from data. Delivery status is not payment approval.

7

Update Card Acquisition amounts

Move Card Acquisition currency, tipAmount, and totalAmount into TransactionDetails.

8

Move sale terminal data

Move SaleTerminalData into Context.SaleContext.

9

Update the protocol version

Send the 5.1-WL2.x.x protocol version required by the latest API specification in the request header. Here, x.x denotes the version numbers; do not send it literally.

Version 2.1.3

App release date: October 13, 2026

This release adds card-reader services, expands payment responses, and changes validation and compatibility rules. Features depend on the app version installed on your terminal and the capabilities of its payment application.

Compatibility changes

• Full Nexo JSON names required: Deprecated abbreviated enum values are no longer supported. Before upgrading, replace values such as SFSQ with SaleFinancialServiceRequest and PRCP with PrinterReceipt throughout your requests and response handling. This change concerns values inside JSON messages; the /api/v1 endpoint remains available.
• Stricter amount validation: Request amounts are converted to payment-app minor units using the currency's supported decimal precision. Values with excessive precision or outside the supported amount range are rejected. Check the precision of the amounts your integration sends.
• Environment selection: Production-store builds use the production environment. Test-store builds support IACC and development. Restored configuration follows the same restrictions.

New capabilities

• Card-reader device services: Initialize supported ICC/NFC readers, exchange APDUs, and power off the reader. Power-off cancels an in-progress initialization and returns an Aborted result for it.
• WPI compatibility: WL1 requests retain legacy mapping, while WL2 requests use current mapping. The payment application's WPI envelope is negotiated independently. Both mappings require the full Nexo JSON names described above.
• Additional payment identifiers: Payment responses can include online tokens and external transaction identifiers in TransactionDetails.AdditionalInformation when supplied by the payment application.
• Reversal response details: Reversal responses include TransactionResponse with the authorization result and authorization code when available.

Bug fixes

• Invalid Nexo enum errors identify the affected field and suggest the full JSON name for recognized legacy values.
• UI response flows prevent accidental back navigation from producing unintended responses.
• Processing screens appear after short input timeouts when requested.
• Text wrapping and identifier visibility improve on smaller terminals.

Service improvements available from October 21, 2026

These service improvements include request tracking and duplicate handling on API v2. They are available independently of the terminal app upgrade; installing app 2.1.3 is not required to receive these service changes.

Request tracking and duplicate handling

• Header.ExchangeIdentification identifies a transaction within a merchant. Repeating a processed exchange can return its recorded response without executing it again. In-flight synchronous duplicates return HTTP 409; asynchronous repeats return the existing transaction state and replay a recorded response to the webhook when available.
• New asynchronous requests return HTTP 202 with transactionId, status, and requestId at the response root. Existing exchanges return HTTP 200 with their current state. Exchanges eligible for retry can be accepted again.
• GET /api/v2/merchants/{umid}/transactions/{transactionId}/status returns the terminal identifier, delivery state, and recorded response payload when available. Use the original ExchangeIdentification as transactionId.

Integration update: Read asynchronous acknowledgements from the response root and handle both 202 and 200. The acknowledgement and transaction-status response are exceptions to the usual v2 data envelope. PROCESSED means a terminal response was recorded; it does not mean the payment was approved. NO_RESPONSE_FROM_TERMINAL leaves the payment outcome unknown. Read the Nexo response for the financial outcome.

See asynchronous acknowledgements, duplicate handling, and status lookup for examples.

Other service improvements

• HMAC-key management supports creation, inspection, rotation, and revocation; API-key expiry notifications have been added.
• Corrects collection/array serialization in v2 success envelopes.
• Improves asynchronous request dispatch and terminal acknowledgement tracking.

Integration actions

There are four checks for existing integrations. Changes are needed only where your integration uses the affected behavior.

Check	Applies when	Action
Nexo names	Requests or response handling still use abbreviated values.	Before upgrading to app 2.1.3, use full JSON names such as SaleFinancialServiceRequest and PrinterReceipt.
Amount precision	Your integration sends amounts to the terminal app.	Check amounts against the currency's supported decimal precision and amount range. Correct values that previously relied on rounding or truncation.
Asynchronous acknowledgements	Your integration uses API v2 asynchronous operations.	Handle 202 for accepted work and 200 for an existing exchange. Read transactionId, status, and requestId from the response root. Continue reading the payment outcome from the Nexo result.
Retries and missing responses	Your integration retries v2 operations or recovers a missing result.	Keep the original ExchangeIdentification when resending the same operation. Handle 409 for an in-progress synchronous duplicate, accept duplicate webhook deliveries safely, and use transaction-status lookup to recover a missing result. Do not create a new payment identifier solely because a response is missing.

The new card-reader operations, additional response fields, and key-management capabilities can be adopted when needed. They do not add mandatory integration steps. When installing the app, also select the build for the intended environment: production-store for production, or test-store for IACC/development.

Update history

Version 2.1.2 — App release date: September 8, 2026

Updates

• Receipt delegation now covers end-of-day reconciliation, terminal configuration, and acquirer initialization when PrinterReceipt is advertised in SaleCapabilities.
• Custom screen requests received while a payment is in progress return Busy, preventing screens from covering the payment application.

Bug fixes

• Concurrent payment-app requests are serialized, delayed responses stay correlated with their requests, and active transactions remain abortable.
• Timeout responses retain the original payment session information and report a transaction timeout. Abort requests target the referenced payment session.
• UI lifecycle failures return explicit failure responses. Stale timeouts and callbacks no longer complete a newer screen request with empty input.
• Normal screen transitions no longer accidentally open the configuration screen.
• Long single-selection rating titles wrap correctly on S1P terminals.

Version 2.1.1 — App release date: August 26, 2026

Features

• Adds phone-authorized payments, force acceptance, and unreferenced cancellation, subject to payment-application support.
• Supports MultiAccountIndex on payment, pre-authorization, follow-on payment, and refund request mappings. ProductSelection is supported for payment and pre-authorization.
• Extends financial responses with additional payment details, including surcharge, customer language, referral telephone number, phone-authorization and force-acceptance indicators, account type, and selected product when provided by the payment application.
• Extends PaymentInformationResponse with terminal software/model, language/currency settings, and payment/receipt capabilities when available.

Bug fixes

• Corrects the accessibility payload sent to the payment application and supplies defaults for omitted accessibility settings.
• Improves empty-screen guidance and available actions. Blank action definitions no longer create empty buttons.
• Prevents screen blinking and empty responses during configuration changes on S1U2 M4 terminals.
• Prevents repeated display of in-flight InfoScreen requests with the same exchange identifier and improves long information text rendering.

Version 2.1.0 — Release date: August 5, 2026

This release adds new UI and payment-request capabilities, tightens request validation, and fixes a number of mapping and error-handling issues.

Features

• Accessibility settings on payment requests

  Accessibility settings can now be supplied on a payment request through the AccessibilitySettings extension on PaymentTransaction, and are applied to the payment flow on the terminal.

• Seamless ECR-initiated flows

  ECR-initiated flows now render every step on a single, state-driven screen instead of opening a new screen per step, removing the visible flash between steps. Set ShowProcessingScreen in the request body to display a processing spinner between steps for up to 30 seconds.

• Secondary button on image screens

  Image screens now support a secondary action button, enabling richer interaction flows.

• Reconciliation receipt format handling

  Reconciliation flows now support both structured JSON receipts and formatted receipt content.

• Text field on info screens

  Info screens now support a dedicated text field.

Updates

• TransactionReference validation and normalisation

  Payment requests with a null, empty, or literal "Null" NEXO TransactionReference are now rejected, and valid references are trimmed before they are forwarded.

• Empty ProtocolVersion validation

  Requests with an empty NEXO ProtocolVersion are now rejected with a protocol-version error instead of being processed.

Bug fixes

• Multi-option screens require unique IDs

  Multi-option selections now accept only unique option IDs, preventing ambiguous selections.

• Card Acquisition response mapping

  Card Acquisition responses now return the response ServiceContent values (FinancialCardAcquisitionResponse) instead of echoing the request values (FinancialCardAcquisitionRequest).

• Keep-alive UI after reboot

  Keep-alive UI state is now retained correctly after a device restart.

• Clearer missing mandatory field errors

  Validation errors for missing mandatory fields are now formatted more clearly.

• Expanded error reasons

  Added missing reasons for invalid password, internal error, invalid key, transaction timeout, and encryption failures, so more error conditions now return an accurate reason.

• Response service type fallback

  The response service type is now resolved with a correct fallback when it is missing from the WPI response.

• Graceful handling of missing payment-app envelope fields

  When the payment app returns a response with missing WPI envelope fields, those failures are now converted into Nexo-friendly rejection responses instead of surfacing raw errors.

Version 2.0.0 — major release — Release date: July 1, 2026

The following describes the initial 2.0.0 release. For the current asynchronous acknowledgement and status formats, see the service improvements available from October 21, 2026.

This is a major release. It introduces a new API version (/api/v2) with breaking changes to the request and response format. Existing integrations on /api/v1 continue to work unchanged, but moving to /api/v2 requires the updates marked Breaking change below. A migration checklist is provided at the end.

Features

• New API version with a consistent response envelope

  A new /api/v2 path set is available. Every successful v2 response is now wrapped in a predictable envelope — the business payload sits under data, alongside a requestId you can use for support and log correlation.

  Breaking change: on /api/v2, read the payload from body.data instead of the root of the response, and switch your URL prefix from /api/v1/... to /api/v2/....

• Standardised error responses

  All v2 errors now share one shape: a human-readable message and the requestId.

  Breaking change: the v1 code field is gone in v2. Read errors from body.message and remove any dependency on body.code.

• Asynchronous processing acknowledged with 202 Accepted

  Requests that can't be answered immediately are acknowledged with 202 Accepted carrying only a requestId; the terminal's response is delivered later to your configured WebhookUrl, wrapped in the same { data, requestId } envelope as synchronous responses.

  Breaking change: handle 202 Accepted for async flows and consume the webhook payload from data.

• Mandatory Sales System identification

  Every v2 request must now identify the calling software. Header.SalesSystemInfo is required and must include an IntegratorId (max 140 characters) and at least one SaleSoftware entry, each with a Type and a Status.VersionNumber.

  Breaking change: add a complete SalesSystemInfo block to every request. Missing or incomplete blocks are rejected with 400.

• Stricter request validation for exchange identification

  Header.ExchangeIdentification is now validated as a UUID on v2.

  Breaking change: generate a valid UUID for ExchangeIdentification on every request. Non-UUID values are rejected with 400.

• Card Acquisition amounts restructured

  currency, tipAmount, and totalAmount in Card Acquisition requests have moved into a new TransactionDetails object, aligning Card Acquisition with the standard PaymentRequest structure.

  Breaking change: move these three fields into TransactionDetails when building Card Acquisition requests.

• Sale terminal data moved to Sale Context

  SaleTerminalData now lives under Context.SaleContext to match the Nexo Retailer specification. The previous location is still read as a fallback and logged as deprecated. Support will be removed without further notice from this one when using v2.

  Breaking change (with fallback): move SaleTerminalData into Context.SaleContext. The old location keeps working for now but is deprecated and will be removed.

• DCC refund support

  Refunds can now carry dynamic currency conversion data via a new DCCRefund structure in PaymentTransaction, including rateReferenceIdentifier and originalTransactionDate.

• Card expiry date in financial responses

  Successful financial transactions now return the card expiryDate (YYMM), mapped to Environment.Card.PlainCardData.ExpiryDate in the Nexo response.

Bug fixes

• Graceful handling when the payment app is missing

  The app now handles the case where the WPI payment app is not installed, preventing protocol-level details from surfacing in the UI.

• Correct authorisation mapping for transactions requiring signature

  Signature-flow responses now map from the WPI result correctly (success → Approved, failure → Declined) and no longer return Suspended for successful signature transactions.

• Abort responses

  The app now sends an abort response to the caller whenever possible.

• Loyalty card NFC handling

  NFC handling for loyalty card reading has been improved so the flow proceeds smoothly.

Migration checklist (v1 → v2)

1. Switch the URL prefix from /api/v1/... to /api/v2/....
2. Generate a UUID for Header.ExchangeIdentification on every request.
3. Add a Header.SalesSystemInfo block (IntegratorId + at least one SaleSoftware with Type and Status.VersionNumber). Request the new values from your contact within Worldline.
4. Read successful payloads from body.data.
5. Read errors from body.message; remove any body.code lookup.
6. Handle 202 Accepted for async requests and consume the webhook payload from data.
7. Move Card Acquisition currency / tipAmount / totalAmount into TransactionDetails.
8. Move SaleTerminalData into Context.SaleContext.
9. Send ProtocolVersion: "5.1-WL2.0.0" in the request header.

Version 1.5.0 — bug fixes, feature, updates — Release date: March 31, 2026

Features

• Card Acquisition support

Integrators can now trigger a Card Acquisition request through the API, allowing the terminal to read card data without initiating a payment. This supports use cases such as loyalty enrolment and card-based identification.

• Idempotency cache for duplicate request handling

Duplicate requests with the same exchange identification are now detected and handled automatically. In-flight duplicates wait for the original response; already-completed duplicates return the cached response immediately. Cached entries are retained for 7 days.

Bug fixes

• Fix app not restarting after an upgrade

The app now listens for the MY_PACKAGE_REPLACED broadcast to automatically restart after an update, ensuring the service resumes without manual intervention.

• Fix payment brand name in Card Acquisition responses

The payment brand in Card Acquisition responses now correctly uses the application label from the payment app instead of a hardcoded value.

Updates

• Migrate to Koin for dependency injection

The app dependency injection has been migrated from manual wiring to Koin with annotation-based modules, improving maintainability and reducing boilerplate across all layers.

Version 1.4.6 — feature — Release date: March 11, 2026

Features

• Print mixed content in a single receipt request

You can now combine text, QR codes, and barcodes into one print request. This eliminates the risk of incomplete receipts caused by multiple separate requests failing midway.

• Structured JSON receipt format

Receipts can now be delivered in a rich, structured format alongside the standard plain-text format. Both can be requested at the same time, giving integrators full flexibility in how they display and process receipt data.

• Open the payment menu via API

The payment solution menu on the terminal can now be triggered directly through an API call, making it easier to integrate terminal navigation into point-of-sale workflows.

• Control whether the terminal prints the receipt

Integrators who manage their own receipt printing can now instruct the terminal to skip printing on its side, preventing duplicate receipts. The receipt data is still returned in the response regardless.

• Transaction reference echoed back in responses

Every transaction response now includes the same unique reference ID as in the original request, making it straightforward to match requests to responses and supporting idempotency.

• Terminal settings survive app downgrades

Terminal configuration is now backed up to the cloud. If the app is downgraded and reinstalled, which previously wiped all local settings, the terminal can restore its configuration automatically on first launch, with no manual setup needed.

Version 1.4.5 — bug fixes, feature — Release date: March 4, 2026

Features

• Exponential backoff retry with 5 attempts starting in 2 seconds to resend the dropped messages
• Persist the unprocessed messages with automatic resend on reconnect
• Implement a stateless abort broadcast to cancel in-flight requests
• Add print receipt mapping with SmartPOS API
• Add RetailerPaymentResult with status messages request
• Return tip amounts in NEXO PaymentResponse
• Improve WPI Intent Action for Admin Requests
• Add support for refund message status and repeated reversal response

Bug fixes

• Resolve missing webhook responses
• Enhance error remark handling in the WPI response
• Map NEXO AllowedEntryMode to WPI useManualPanKeyEntry
• Map NEXO line width to WPI receiptWidth
• Map WPI DCC fields to NEXO CurrencyConversionResult
• Echo full Cashier-ID in NEXO responses

Version 1.4.4 — bug fixes, feature — Release date: January 9, 2026

• Feature
  • TAPI app now runs in the background automatically and remains active after device reboot.
• Bugfix
  • Fix the Abort transaction.

Version 1.4.3 — bug fixes, feature, updates — Release date: January 9, 2026

Features

• Adds support for Administrative Acquirer Initialization (ACQI) and Terminal Configuration (TCFG) requests.
• Adds support for the "DocumentQualifier" and "MessageDestination" fields in Nexo Responses in JSON tags format (e.g., "CustomerReceipt" instead of "CRCP").

Bug fixes

• CreationDateTime header now reflects the time the response was created, not the time the initial request was sent.
• Fixes OriginalPaymentTransaction.TransactionType being "Error" in the Reversal Responses.
• Makes the font size in the EV screens resizable to adapt to the default system font size.

Updates

• Enhances navigation experience in the app.
• Improves the error response reason to be more informative.

Version 1.4.2 — updates — Release date: September 16, 2025

Version 1.4.1 — bug fixes, feature

Features

• Enables the clients to open customizable screens meant for EV Charger use cases. More information here [TBA].
• Adds support for cancelling a Reservation (Pre Authorization).
• Adds the missing ApplicationIdentifier field to the Nexo Card model, enhancing payment transaction tracking capabilities.

Bug fixes

• On S1U2 terminals, opening the menu with the physical button or emulator Menu button no longer loops back to idle; the menu now stays open until you close it.
• Credentials no longer disappear after reboot by preserving UMID and UTID across restarts.
• Adds flexible currency support to the amount screen; optional currency field (up to 4 characters, € / EUR), and hides currency in the response input to ensure correct amounts across EU currencies.
• Fixes WebhookUrl and NumberOfRetries missing from the rejection response headers.
• Adds support for Nexo JSON tags for the EV Charging feature.
• Fixes UI related requests not following the Nexo Specification regarding the placement of the fields.

Version 1.3.0 — updates

Updates

• Switches from Nexo Retailer abbreviations to the full code names for better readability in our APIs (e.g., SFSQ to SaleFinancialServiceRequest).

Version 1.2.3 — bug fixes, feature, updates

Features

• Adds support for async payment.
• Adds support for Follow On Debit and Follow On Credit.

Updates

• Adds support for CardDataEntryMode = PHYS for purchase requests; maps to WPI manual entry mode and enables manual card data entry in purchase flows.
• Removes SupplementaryData from ReconciliationResponse and replaces it with PaymentReceipt.
• Removes receipt line width support; the LineWidth field is no longer sent in requests for Castle and Integrated terminals.
• Adds new App & Notification icon.

Bug fixes

• Aborted transactions now return ABRT/Aborted instead of NALW/NotAllowed, improving Cancel/Abort flow.
• Fixes intermittent connection issues to improve reliability.
• Fixes Terminal App navigation to Idle after a connection is established from the Configuration screen (no longer stuck in setup).
• Fixes the visibility of the current configuration when reconfiguring the Terminal App.