Appendices

Glossary

Release notes

Glossary

Abbreviation	Description
Asynchronous Processing	A pattern where a request is acknowledged immediately (e.g., 202 Accepted), and the final result is delivered later via a Webhook.
Authentication (Bearer Token)	A security method using an API key in the Authorization header to prove identity and access API resources.
Cloud-to-Cloud	An architectural model where communication between your backend and the terminal is brokered entirely through Worldline's cloud.
Custom UI	A feature that allows you to trigger interactive, branded screens (e.g., Signature, QR, Info Table) on the terminal display.
ECR	Electronic Cash Register; the system at the point of sale that initiates transaction data.
Exchange Identification	A unique, integrator-generated ID used to match a specific request with its corresponding response.
HSTS	HTTP Strict Transport Security; a policy mechanism that forces communication over HTTPS to prevent downgrade attacks.
MessageFunction	A message header field defining the category of the request (e.g., SaleFinancialServiceRequest).
Nexo Retailer v5.1	The industry-standard protocol defining the structure and hierarchy of JSON payment messages.
POI	Point of Interaction; the physical payment terminal hardware.
Reconciliation	An administrative process to close the business day, verify totals, and balance logs.
Synchronous Processing	A pattern where the client waits for the HTTP connection to complete until the transaction result is returned.
Terminal API App	The software installed on the terminal that bridges the physical device and the Worldline cloud.
TID	Terminal ID; the unique identifier assigned to a specific payment terminal.
UMID	Unique Merchant ID; the identifier assigned to a merchant account for routing and billing.
Webhook	A mechanism allowing the Worldline platform to push transaction results to a URL on your server immediately upon completion.

Release notes

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.

Update history

Version 2.0.0 — major release — Release date: July 1, 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). For more information, check out our migration plan guide .

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.