Skip to main content

Overview

Introduction​

The Terminal API enables secure communication between merchant applications and Worldline payment terminals through REST APIs. Use the API to initiate and manage payments, refunds, pre-authorisations, reversals, and reconciliation operations.

The API supports both synchronous and asynchronous transaction processing and uses Nexo Retailer V5 messages for payment data exchange. Authenticate requests using JWT bearer tokens and receive transaction results through API responses or webhook callbacks.

Use cases​

Retail and Point-of-Sale Payments

Process in-store card payments through integrated POS and payment terminal systems.

Hospitality and Restaurant Payments

Accept payments in hospitality environments with support for tableside, counter, and service-based transactions.

EV Charging Payments

Enable secure payment acceptance at electric vehicle charging stations through integrated payment terminals.

Self-Service and Unattended Commerce

Support customer-operated payments in kiosks, vending machines, parking systems, and other unattended environments.

Customer Engagement on Payment Terminals

Display custom messages, prompts, and branded content on payment terminals during customer interactions.

Transaction Tracking and Reconciliation

Monitor transaction status, retrieve payment details, and simplify reconciliation processes.

Real-Time and Asynchronous Transaction Processing

Support both immediate transaction processing and asynchronous workflows for long-running payment operations.

Nexo Retailer V5 Protocol Payment Integration

Integrate POS, ECR, kiosks, and payment applications using industry-standard Terminal API protocols for seamless payment processing.

Retail and POS payments​

1
Initialize Client
  • Set connection timeout parameter to 5 seconds for fast checkout queues.
  • Toggle "unattended_mode": false to enable merchant clerk prompts.
2
Push Bill Total
  • Fire a POST request to /v1/terminal/intent.
  • Pass "intent": "IMMEDIATE_AUTH" with the exact transaction balance.
3
Authorize Card
  • Prompt the customer to tap, insert, or swipe their card.
  • Terminal processes the EMV data and checks for immediate bank approval.
4
Settle Instantly
  • Read the synchronous success token from the gateway response.
  • System clears the basket layout with zero persistent token creation.
5
Close Transaction
  • Trigger the local hardware register printer to issue a physical receipt.
  • Reset the terminal screen interface to the default idle welcome screen.

Hospitality and restaurant payments​

1
Open Order

Create an order and maintain an open transaction while the customer is dining.

2
Request Pre-Authorisation

Send a pre-authorisation request to reserve funds on the customer's card.

3
Authorize Card

Customer taps, inserts, or swipes their card.

4
Adjust Final Amount

Update the final amount to include additional items, service charges, or gratuities.

5
Capture Payment

Submit the final capture request and complete the transaction.

EV charging payments​

1
Initialize Client
  • Set connection timeout parameter to 45 seconds.
  • Toggle "unattended_mode": true to suppress clerk prompts.
2
Request Deposit
  • Fire a POST request to /v1/terminal/intent.
  • Pass "intent": "PRE_AUTH" with a fixed deposit amount.
3
Authorize Card
  • Prompt the driver to tap or insert their card.
  • Terminal generates a temporary token valid for 3 hours.
4
Dispense Power
  • Read the payment_intent_id from the success response payload.
  • Trigger the physical kiosk hardware switch to dispense electricity.
5
Final Capture
  • Calculate final cost when the driver unplugs their vehicle.
  • Fire a POST /v1/terminal/intent/{id}/capture with the final amount.
  • Gateway clears the final total and releases remaining held funds.

Self-service and unattended commerce​

1
Initialize terminal

Configure the terminal for unattended operation.

2
Display purchase options

Allow customers to select products or services.

3
Initiate Payment

Send a payment request for the selected item.

4
Authorize Transaction

Customer presents a payment method.

5
Deliver Service

Dispense the product or activate the purchased service.

Customer engagement on payment terminals​

1
Display Custom Screen

Present promotional or informational content on the terminal.

2
Collect Customer Input

Capture selections, ratings, signatures, or survey responses.

3
Process Response

Receive customer interactions through Terminal API responses.

4
Trigger Business Action

Apply rewards, discounts, or service adjustments.

5
Complete Experience

Return the terminal to the transaction or idle state.

Transaction tracking and reconciliation​

1
Record Transaction

Submit payment requests through Terminal API.

2
Track Status

Monitor transaction progress using synchronous responses or webhooks.

3
Collect Results

Receive approval, refusal, or pending status information.

4
Perform Reconciliation

Request settlement and reconciliation information.

5
Validate Totals

Compare transaction records with settlement reports.

Real-time and asynchronous transaction processing​

1
Submit Request

Send a payment or service request.

2
Choose Processing Mode

Use synchronous or asynchronous processing.

3
Monitor Progress

Track transaction execution.

4
Receive Results

Collect results through the API response or webhook callback.

5
Update Systems

Synchronize transaction status with business systems.

Nexo retailer payment integration​

1
Adopt the Nexo Standard

Use the Nexo Retailer V5 message model as the foundation for payment communication.

2
Build Standard Messages

Create payment, refund, reversal, and reconciliation requests using the Nexo data model.

3
Send Requests

Transmit Nexo messages through Terminal API REST endpoints using HTTPS.

4
Process Responses

Receive Nexo-compliant responses through synchronous API calls or asynchronous webhooks.

5
Maintain Compatibility

Reuse existing Nexo knowledge and integrations while supporting future protocol enhancements and platform updates.

Next steps​

What's new​

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.

Refer to the Release Notes for details about the latest features, enhancements, bug fixes, and updates.