Cloud Integration | Terminal API

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	Request was successfully processed.	Request received successfully and sent to the terminal.
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.

These standard status codes provide all the information needed to determine the outcome of an API call and guide appropriate error handling. Ensure your integration logic accounts for these responses to maintain resilience and ensure predictable behavior in production environments.