Connection Models

The API can be implemented in two modes, Synchronous mode (blocking) and Asynchronous mode (non-blocking).
Choosing the right connection model for you depends on your use-case. Our recommendation for most integrations is to use the Asynchronous mode, even if you don’t need the additional features it will limit the risk for errors in a connection with intermittent problems as the connection isn’t held open for long periods of time. If you have merchants with high transaction volumes (i.e. lunch restaurants) and want to prioritize transaction speed then synchronous mode is faster, this will however require more from your application to make sure that transaction data isn’t lost in case of a communication error

Synchronous mode link

Synchronous mode is the fastest way to implement. In synchronous mode, the operations will be sent to one terminal from one ECR and while the operation is performed, the connection must be open. Once the terminal has completed the operation, the result can be returned to the ECR and the connection closed.

A full synchronous implementation will need to implement the operations tagged by Synchronous and Modeless Operations.

Asynchronous mode link

Asynchronous mode is a distributed mode where the ECR requests an operation, it is acknowledged by the terminal, and then the connection is closed. The ECR then “polls” for a status: If the terminal has completed the operation, the response is returned and the terminal will regard the operation as completed. This distributed behavior will allow operations to be initiated by one ECR and completed by another.

A full asynchronous implementation will need to implement the operations tagged by Asynchronous and Modeless Operations.

Rate limits link

While the API itself does not have a specific rate limit you should consider the following when sending requests to avoid flooding the HTTP server which can in some circumstances degrade the responsiveness.

Interval vs. Sequential link

A common approach would be to make a request, sleep for a set interval and then make another request, this leads to a lot of overhead and the risk of executing parallel requests if the sleep interval is set too tightly. Both of which would negatively impact terminal performance.

The recommended implementation is to make your requests sequential - Wait for the response of your first request before sending your next request:

It could look something like this:

Function pay(operationId):

    // Start a payment request and wait for its response, 200 indicates payment started successfully
    paymentResponseCode = startPayment(operationId)

    Loop:
        // ** OPTIONAL: Check if /Abort/{operationId} was called from the application, 
        // it should be done asynchronously as when you're firing requests this tightly it will almost certainly fail otherwise.

        // Call checkStatus(), which calls /PaymentsAsync/{operationId}/status and wait for its result
        statusResult = await checkStatus(operationId)
        // Call checkDialog(), which calls /Dialogs/{operationId} after checkStatus() completes
        dialogResult = await checkDialog(operationId)


        // Repeat the loop until checkStatus() returns a status code of 200, 
        // indicating the payment has been finished (this does not reflect if the payment was approved or denied)
        If statusResult.statusCode == 200:
            Exit Loop

    End Loop

 

While performance will vary between terminal generations and connection interfaces, this approach should let you get the most out of each device!

Time resolution link

We have observed cases where certain time libraries and platforms (such as Python’s datetime.now() on Windows) rely on CPU cycles rather than real-time clocks, which can sometimes result in the same timestamp being returned twice when response times are faster than approximately 16 milliseconds.

This will throw a HTTP:401 response with the message: Timestamp must be more recent than last communication. Errors like these can safely be stepped over.