Cloud integration

Worldline Terminal API is designed to support modern, cloud-native integrations, enabling secure, scalable, and reliable communication between your backend services and our terminal infrastructure — without the need for local networking or direct terminal access.

This page provides a high-level overview of how the cloud-to-cloud model works, how we ensure secure communications, and how to interpret server-side response codes.

Cloud-to-cloud architecture overview

Terminal API leverages a cloud-to-cloud architecture, meaning that the communication between your system and the payment terminal is brokered entirely through secure HTTPS requests from your servers to Worldline's cloud environment.

Key architectural principles include:

• Direct API integration from your server to Worldline payment terminals — no local server or device middleware required.

• Communication is initiated by your system and relayed to the terminal through our cloud routing infrastructure.

• Asynchronous responses are delivered via webhooks to a callback URL provided with each transaction request — no polling is required.

Security considerations

• HTTPS with HSTS: All API traffic is encrypted via HTTPS, with HTTP Strict Transport Security enforced to prevent downgrade attacks.

• API Key Authentication (Bearer token): Each integration uses a unique API key. This key must be sent in every request as a Bearer token, for example:

  Authorization: Bearer <YOUR_API_KEY>

Understanding server-side response codes

When integrating with the Terminal API over HTTPS, your system will receive standard HTTP status codes in response to every request. These codes indicate whether the request was successfully processed, rejected due to a client-side issue, or failed due to a server-side error.

Understanding and correctly interpreting these responses is key to handling retries, error logging, and exception flows in a robust and predictable manner.

Common HTTP status codes

These codes are returned at the HTTP protocol level, primarily indicating whether the API endpoint could process the request:

HTTP Code	Meaning	When it Occurs
200 OK	The endpoint returned a result or an existing exchange.	A synchronous terminal response, an asynchronous duplicate acknowledgement, or a successful status lookup. Inspect the body; this is not payment approval.
202 Accepted	Work was accepted or a synchronous wait ended without a terminal result.	New asynchronous work returns root-level transactionId, status, and requestId. A synchronous timeout acknowledgement has no Nexo business payload.
409 Conflict	A synchronous exchange is already in progress or cannot be replayed.	Look up the original exchange before deciding how to recover.
301 Moved Permanently	The resource has been moved.	Redirects are rarely used in this context, but may appear in test environments.
400 Bad Request	Malformed syntax or invalid parameters.	Invalid JSON.
401 Unauthorized	Missing or invalid API key.	Make sure your request includes the correct authentication header.
404 Not Found	Endpoint does not exist.	Can be caused by several reasons: incorrect URLs, API versioning issues, as well as invalid or not connected Terminal IDs.
408 Request Timeout	Server timed out waiting for the request.	Could indicate latency issues.
429 Too Many Requests	Rate limit exceeded.	Apply exponential backoff and retry logic.
500 Internal Server Error	Unexpected error on the server side.	Retry with backoff or contact support.
503 Service Unavailable	Temporary unavailability (e.g., maintenance).	Check the status page or retry later.

HTTP status codes describe API handling. Determine payment approval from the Nexo business response. Keep the original ExchangeIdentification when recovering a missing response, and use transaction-status lookup. PROCESSED means a terminal response was recorded; NO_RESPONSE_FROM_TERMINAL leaves the payment outcome unknown.