Terminal Terminal

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.

  • Resiliency on unstable links: If ECR or terminal connectivity is intermittent, requests can be queued and the eventual result delivered via webhook when connectivity is restored.

3. General usage

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 does basic JSON validation and enqueues the work; responds 202 Accepted .

  • Terminal processes the request.

  • When finished, the platform sends the result of the payment operation using an HTTP POST request (an example can be found in the Responses section) to your webhook URL.

  • 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 NumberOfTimes.

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, (min:0, max:3) in case of negative value the API will return an exception.

    • 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.