Skip to main content

Cloud Integration

Before sending your first request, complete the following steps. Worldline Terminal API enables secure cloud-to-cloud communication between your backend services and payment terminals, eliminating the need for local networking or direct terminal access.

Configure your cloud-to-cloud architecture
Secure your communications
Interpret server-side response codes
Use the Nexo protocol
Implement the messaging backbone
Maintain compatibility
Next Steps - Initiate payment

Configure your cloud-to-cloud architecture​

Follow these steps to integrate your systems:

  1. Send HTTPS requests from your servers to the Worldline cloud environment.
  2. Ensure your system initiates all communication; our routing infrastructure relays these requests to the target terminal.
  3. Use webhooks to receive asynchronous responses. Provide a callback URL with each transaction request to avoid manual polling.

Secure your communications​

Maintain security throughout your integration:

Enforce encryption: Use HTTPS for all API traffic. Enable HTTP Strict Transport Security (HSTS) to prevent downgrade attacks.

Authenticate requests: Include your unique API key as a Bearer token in the header of every request: Authorization: Bearer <YOUR_API_KEY>

Interpret server-side response codes​

Handle API responses by monitoring standard HTTP status codes. Use these codes to manage retries, logging, and error flows.

HTTP CodeMeaningAction
200Request processed successfully.Proceed with your transaction flow.
301Resource moved.Verify the endpoint URL.
400Malformed syntax.Check your JSON structure.
401Unauthorised.Include a valid API key in the request header.
404Endpoint not found.Check the URL, API version, or Terminal ID.
408Request timeout.Check for latency issues.
429Too many requests.Apply exponential backoff and retry.
500Internal server error.Retry the request or contact support.
503Service unavailable.Monitor the status page and retry later.

Use the Nexo protocol​

Worldline uses the Nexo Retailer V5 protocol as the foundation for the Terminal API. This standard ensures interoperability and simplifies your integration process.

The Nexo Retailer V5 protocol manages real-time interaction between your Point-of-Sale (POS) system and the payment terminal. It standardises the Retailer-to-Acquirer interface for:

  • Payments
  • Refunds
  • Reconciliations

The protocol supports traditional POS terminals, self-service kiosks, and headless checkout systems.

Implement the messaging backbone​

The Terminal API uses Nexo Retailer V5 to define message structures. Follow these requirements to implement the protocol:

  • Use standard message types: Structure your requests using the Nexo data model for PaymentRequest, ReversalRequest, and ReconciliationRequest.
  • Apply JSON wrapping: Although the Nexo standard uses XML, the Terminal API requires you to transmit these messages wrapped in JSON over REST endpoints.
  • Follow the data model: Ensure your messages align with ISO 20022 principles to maintain consistent parsing and validation.

Maintain compatibility​

Because our implementation adheres to the official Nexo Retailer V5 specification:

  • Reuse your existing knowledge of Nexo message formats and terminology.
  • Refer to our documentation for protocol extensions, which allow for additional terminal functionality.
  • Ensure your integration remains compliant with the standards supported by the Nexo community.

Next steps​