Overview of async payment processing

This document defines the asynchronous terminal payment API, describes its functionality, and explains how to use it. It covers the end-to-end workflow, required request and response formats, webhook callback mechanics, retry semantics, validation rules, and guidance for testing and operations. The goal is to enable integrators and operators to implement, configure, monitor, and troubleshoot the API reliably and with clearly defined expectations.

1. When and where to use the asynchronous API

• Requests should generally be handled asynchronously, as some operations may take time to complete, and it is not necessary to wait for an immediate response. This is particularly applicable to complex payment requests, processing tasks, or reconciliation operations.

• Reliability on unstable networks or remote terminals: ECRs may operate offline or on unstable networks. An asynchronous API allows the device to submit a request when connectivity is available and receive the result later via webhook, without blocking the operator or requiring persistent connectivity.

2. Why webhooks?

• Benefits of Webhooks: Webhooks allow long-running tasks to be offloaded and results to be delivered asynchronously - eliminating the need for polling and avoiding blocked threads.

• Recovery from interrupted communication: retain the exchange identifier and use transaction-status lookup to recover a missing result. A disconnected terminal can return 404 before work is accepted; asynchronous processing does not guarantee delivery to an offline terminal.

3. General usage

POST/api/v2/merchants/{umid}/terminals/{utid}/payments

Use protocol 5.1-WL2.1.1, a UUID for Header.ExchangeIdentification, and the required Header.SalesSystemInfo. Include Header.WebhookUrl and Header.NumberOfRetries. A complete v2 JSON example is available in Understanding our protocol.

You do not hold the HTTP connection open until the terminal is done. Instead:

• ECR sends an asynchronous request to the Terminal API, targeting a specific terminal ( UTID ) and merchant ( UMID ).

• API validates the request and claims its exchange identifier. New work receives 202 Accepted; an existing exchange receives 200 OK with its current state. Read transactionId, status, and requestId at the acknowledgement root. Acknowledgements do not contain the payment result.

• For newly accepted work, the terminal processes the request. An existing in-progress exchange continues without starting a second operation.

• When finished, the platform sends the result of the payment operation using an HTTP POST request to your webhook URL. The v2 callback wraps the Nexo message in data, alongside requestId, just like a synchronous v2 response.

• In the event of a failure to send the response to the webhook URL, the service will attempt to resend it a number of times equal to the value of NumberOfRetries.

Acknowledgements and duplicate requests

On API v2, use a new UUID in Header.ExchangeIdentification for each new operation. Keep that identifier when resending the same operation. The identifier is scoped to the merchant; do not reuse it for another operation or terminal.

Request state	HTTP response	What happens next
New exchange, or an exchange eligible for retry	202 Accepted	The accepted work is dispatched to the terminal.
Existing exchange still in progress	200 OK	The current delivery state is returned; a second operation is not started.
Processed exchange with a recorded response	200 OK	The recorded response is replayed to the webhook.

The acknowledgement fields are at the response root, outside the usual v2 data envelope:

{
  "transactionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "ACCEPTED",
  "requestId": "550e8400-e29b-41d4-a716-446655440001"
}

For example, resend the payment example with the same ExchangeIdentification: an in-progress exchange returns 200 with its current state, while a processed exchange can replay its recorded Nexo response. Keep webhook processing idempotent because a callback may be delivered more than once.

The status field describes delivery and processing. PROCESSED means the terminal answered and its response was recorded. Read the Nexo business response to determine whether the payment was approved. NO_RESPONSE_FROM_TERMINAL leaves the payment outcome unknown; a late terminal response can still arrive. Look up the existing exchange before deciding how to recover, rather than creating a new payment identifier solely because a response is missing.

Looking up a transaction

GET/api/v2/merchants/{umid}/transactions/{transactionId}/status

Use the original Header.ExchangeIdentification as transactionId and authenticate with the merchant's bearer token:

curl --request GET \
  'https://api.terminal.iacc.global.worldline-solutions.com/api/v2/merchants/YOUR_MERCHANT_ID/transactions/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/status' \
  --header 'Authorization: Bearer YOUR_TOKEN'

The response contains utid, status, and responsePayload when a terminal response has been recorded. These fields are at the response root. For example, an exchange still being processed can return:

{
  "utid": "YOUR_TERMINAL_ID",
  "status": "PROCESSING"
}

When present, inspect responsePayload as the recorded Nexo response. An unknown transaction returns 404. Retain the merchant and exchange identifiers when investigating a missing result. Polling is available for recovery; webhooks remain the normal result-delivery mechanism.

The rules above apply to the v2 asynchronous operation endpoints. Synchronous duplicates that are still in progress return 409; completed duplicates can return their recorded response. The payment-abort endpoint has its own acknowledgement behavior and is not gated by this duplicate check.

4. Webhook server requirements

• The value of WebhookUrl (i.e., the server address) must be publicly reachable by the API service over the internet.

• The endpoint should be designed to accept POST requests from the API service and to respond with 20x status codes to acknowledge receipt.

• Webhook requests are sent over HTTPS using openssl libraries. During the SSL handshake, your server must present a valid certificate chain.

5. JSON validity and correct format

• Please, follow the request instructions described here .

• Validation rules you can enforce (recommend adding these in your API spec or schema):

  • NumberOfRetries: integer, required for asynchronous requests. The examples use 1; check the selected API specification for the supported range.

  • WebhookUrl : string, must be a valid URI, must use HTTPS.

6. Practical tips for implementing and testing

• Ensure the JSON is valid and corresponds to the specification .

• Ensure that WebhookUrl is reachable (preferably returning a 20x status code on the first attempt). To verify this, you can use Postman to send a POST request to the WebhookUrl; you should receive a 20x response.