Skip to main content

API Reference

API Specifications​

Supported Versions​

For detailed version changes, enhancements, fixes, and known issues, refer to Release Notes.

Compatibility Notes​

  • Cloud-to-cloud integration uses HTTPS with Bearer token authentication and asynchronous webhook callbacks.
  • Messages follow Nexo Retailer V5 data models.
  • JSON REST endpoints transport Nexo XML payloads.
  • Extensions are non-breaking and documented separately.

Migration Guidance​

  • Migrate existing on-premises integrations to v1.0 cloud endpoints to use webhook-based asynchronous responses.
  • Ensure all Nexo messages remain compliant with the Nexo Retailer V5 XML structure wrapped in JSON.

Endpoints​

Endpoints are categorised by their primary function. Each endpoint page follows a consistent structure to assist with integration.

Reading Endpoint Details​

Each endpoint entry includes:

  • HTTP Method & Path – For example: POST /api/v1/merchants/{umid}/terminals/{utid}/payments
  • Summary & Description – Clarifying when and why to use the endpoint
  • Parameters – umid and utid identify the merchant and terminal
  • Security – All calls require a JWT bearer token
  • Request Body – Must contain a valid Nexo message, such as SaleToPOIServiceRequest or SaleToPOIReconciliationRequest
  • Response – Structured according to Nexo response messages (e.g., SaleToPOIServiceResponse, SaleToPOIMessageRejection)
  • Examples – Real payloads demonstrating request/response behaviour

Because Nexo messages encapsulate both the Header and Body, pay close attention to required fields such as MessageHeader, MessageType and transaction-specific blocks.

Some headers, like NumberOfRetries or WebhookUrl, are only applicable for asynchronous calls.

Payments​

Use this endpoint for standard and asynchronous payment requests, pre-authorisations, and refunds.

  1. HTTP Method: POST
  2. Endpoint URL: /api/v1/merchants/{umid}/terminals/{utid}/payments
  3. Path Parameters:
    • umid: The merchant identifier.
    • utid: The terminal identifier.
  4. Request Headers:
    • Authorization: Bearer <JWT_TOKEN>
    • Content-Type: application/json
  5. Authentication: A valid JWT bearer token is required for all calls.
  6. Request Body: Must contain a valid Nexo message, such as SaleToPOIServiceRequest or SaleToPOIReconciliationRequest.
  7. Response: Returns a SaleToPOIServiceResponse or SaleToPOIMessageRejection.
  8. Notes: Nexo messages encapsulate both the Header and Body. Ensure you include required fields such as MessageHeader, MessageType, and transaction-specific blocks. Note that headers such as NumberOfRetries and WebhookUrl apply only to asynchronous calls.

Screenshot of Terminal API&#39;s API explorer navigation

Admin​

Use this section for administrative or configuration-related actions.

  • HTTP Method: Varies by action (e.g., POST or GET).
  • Endpoint URL: /api/v1/merchants/{umid}/terminals/{utid}/admin/...
  • Authentication: JWT bearer token required.
  • Notes: Refer to the endpoint-specific documentation for exact fields and required values.

Deprecated​

Legacy endpoints are retained for backward compatibility.

Notes: These endpoints remain accessible but are not recommended for new implementations.

Webhook Callback Receiver​

Webhook endpoint for asynchronous responses.

  • HTTP Method: POST
  • Endpoint URL: <base-url>/webhooks/terminal/v1/callback
  • **Path Parameters: **None

Request Headers​

  • Content-Type: application/json
  • X-Worldline-Signature (optional): Used for signature verification when configured.

Authentication Requirements​

Typically none for inbound webhook delivery. Verify authenticity using the configured signature when provided.

Request and Response Notes​

Webhook payloads are delivered as JSON and contain the transaction result and, where applicable, the Nexo Retailer V5 response payload.

Your endpoint should return HTTP 200 within a short timeout period to acknowledge successful receipt.

Sample Webhook Payload​

{
  "TransactionId": "txn-7890",
  "Status": "APPROVED",
  "ResponseCode": "00",
  "Message": "Approved",
  "Timestamp": "2026-08-20T12:35:02Z",
  "NexoV5MessageType": "PaymentResponse",
  "Payload": "<PaymentResponse>...</PaymentResponse>"
}

Response​

{
  "Acknowledged": true,
  "ReceivedAt": "2026-08-20T12:35:03Z"
}

Notes​

The webhook is delivered by Worldline's cloud routing infrastructure. Ensure that the callback URL is publicly reachable and secured. Return HTTP 200 to confirm receipt and implement retry handling for transient failures.

Request Models (SaleToPOIServiceRequest)​

Purpose​

Represents a Nexo Retailer V5 message transported through the Worldline Terminal API.

Structure​

SaleToPOIServiceRequest
├─ MessageHeader
├─ MessageBody
│  └─ SaleToPOIService
│     ├─ MessageCategory
│     ├─ MessageType
│     └─ PaymentRequest (or ReconciliationRequest)

Required Fields​

  • MessageHeader
  • MessageBody
  • Payment or Reconciliation details within MessageBody

Request Example​

{
  "MessageHeader": {
    "ProtocolVersion": "1.0"
  },
  "MessageBody": {
    "SaleToPOIService": {
      "MessageCategory": "Payment",
      "MessageType": "PaymentRequest",
      "PaymentRequest": {
        "Command": "Pay",
        "SaleData": {
          "Amount": 1000,
          "Currency": "EUR"
        }
      }
    }
  }
}

Response Models (SaleToPOIServiceResponse)​

Represents the immediate acknowledgement of a payment request and provides transaction identifiers for follow-up.

Structure​

SaleToPOIServiceResponse
├─ CorrelationId
├─ TransactionId
├─ Status
└─ ResponseMessage

Response Fields​

  • CorrelationId: Correlation identifier matching the request.
  • TransactionId: Server-assigned transaction identifier.
  • Status: Initial processing status.
  • ResponseMessage: Optional human-readable description.

Response Status Values​

  • ACCEPTED: The request has been accepted for processing.
  • REJECTED: The request was rejected.
  • PENDING: Processing is underway and results will arrive through a webhook.
  • FAILED: Processing failed.

Response Example​

{
  "CorrelationId": "abc-12345",
  "TransactionId": "txn-7890",
  "Status": "ACCEPTED",
  "ResponseMessage": "Payment request accepted for processing"
}

SaleToPOIMessageRejection​

Represents rejection of a SaleToPOIService payload.

Structure​

SaleToPOIMessageRejection
├─ CorrelationId
├─ ErrorCode
├─ ErrorMessage

Response Fields​

  • CorrelationId: Correlation identifier matching the request.
  • ErrorCode: Machine-readable error code.
  • ErrorMessage: Human-readable error description.

Message Definitions (SaleToPOIServiceRequest)​

Wraps the Nexo Retailer V5 PaymentRequest inside the JSON transport used by Worldline Terminal API REST endpoints.

Field Definitions​

FieldTypeRequiredDescription
MessageHeaderObjectYesContains protocol and version metadata
MessageBodyObjectYesContainer for the Nexo message
PaymentRequestNexoV5XmlPayloadYesXML payload conforming to Nexo Retailer V5

Data Types​

  • MessageHeader: SaleToPOIHeader
  • MessageBody: SaleToPOIService
  • PaymentRequest: NexoV5XmlPayload

Usage​

Used as the request body when submitting a payment request through the Payments endpoint.

Enumerations (NexoMessageType)​

Defines the supported Nexo Retailer V5 message types.

Supported Values​

ValueDescription
PaymentRequestInitiates a payment
ReversalRequestReverses a previously initiated transaction
ReconciliationRequestRequests reconciliation data

Data Types​

Merchant Identifier​

Internal merchant identifier used within Worldline integration contexts.

  • Format: String
  • Example: MERCHANT-001
  • Validation Rules: Must be non-empty and match a merchant identifier issued by Worldline.

Terminal Identifier​

Identifier for the target payment terminal.

  • Format: String
  • Example: TERM001
  • Validation Rules: Must be non-empty and correspond to a registered terminal.

NexoV5XmlPayload​

XML payload conforming to the Nexo Retailer V5 data model. This message content is transported inside JSON for REST endpoints.

  • Format: XML
  • Example:
<PaymentRequest>...</PaymentRequest>
  • Validation Rules: Must be well-formed XML and conform to the Nexo Retailer V5 XSD schema.

Currency​

  • Description: ISO 4217 currency code for the transaction.
  • Format: String (3-letter code)
  • Example:
EUR
  • Validation Rules: Must be a valid ISO currency code.

ISO Date Time​

  • Description: Date and time in ISO 8601 format used for timestamps in requests and responses.
  • Format: YYYY-MM-DDTHH:mm:ssZ
  • Example: 2026-08-20T12:34:56Z
  • Validation Rules: Must be in UTC and include a timezone suffix.

Quick reference​