Skip to main content

Documentation

Poll - Terminal Response

Check via the poll method if the terminal has responded to a request.

This method is rate limited to 1 request per 500ms per pollId.

Note

  • 404 does not mean failure: A 404 Not Found response means the terminal has not yet reported a result to the CloudLink API. This is normal and expected — you should continue polling. Only stop polling when you receive a 200 OK (response available) or 408 Request Timeout (response expired).

  • Polling and receiving the 200 OK response is the acknowledgment. There is no separate confirmation step (the old /poll/confirmation endpoint is deprecated). If you do not poll within the timeout window (~6 seconds of the terminal responding), the response expires and the terminal may void the transaction.

Parameters
Request Header Parameters
Request Path Parameters

    • pollId

    • The pollId that was provided in the initial request.

200 OK Response

    • eventType

    • The event type triggered by the terminal (e.g., SALE_RECEIVED, SALE_COMPLETED).

    • correlationId

    • The correlation ID provided in the original request.

    • terminalResponse

    • The full terminal response object. Only present when the transaction reaches a final state, such as SALE_COMPLETED or TERMINAL_ERROR.

400 Error Response

    • type

    • Example: https://tools.ietf.org/html/rfc7231#section-6.5.1

    • title

    • Bad Request

    • status

    • 400

    • detail

    • DeviceId not registered

404 Not Found Response

    • Response not yet available

    • The terminal has not reported back yet. This is expected behavior. Keep polling.

408 Request Timeout Response

    • Response TTL expired

    • The response has expired in the queue. Stop polling. Note: the terminal may void the transaction automatically.

429 Error Response

    • message

    • Too many requests

500 Error Response

    • Message

    • Server Error

  • /poll/terminalresponse/{pollId}

  • 200 OK - Response Available

  • curl -X get https://CloudLinkApi/poll/terminalresponse/e02f7fbe-f3a2-49fb-9979-2f240e119499 \
-H 'X-API-KEY: your-access-key-here'
  • {
  "eventType": "SALE_COMPLETED",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "terminalResponse": {
    "cardholderReceipt": "CARDHOLDER RECEIPT\n\nAMOUNT: 10.00 EUR\nCARD: ****1234\nAUTH: 123456\nREF: ABC123",
    "merchantReceipt": "MERCHANT RECEIPT\n\nAMOUNT: 10.00 EUR\nCARD: ****1234\nAUTH: 123456\nREF: ABC123",
    "responseCode": "00",
    "result": "APPROVED",
    "transactionCancelled": "false",
    "cardTypeExtra": "1",
    "authorizationCode": "123456",
    "amount": "1000",
    "cardPan": "****1234",
    "stan": "123456",
    "terminalId": "TERM001",
    "merchantId": "12345678",
    "softwareVersion": "1.0.0",
    "retrievalReferenceNumber": "ABC123"
  }
}

  • 400 Poll Terminal Response Rejected - Unauthorized

  • curl -X get https://CloudLinkApi/poll/terminalresponse/e02f7fbe-f3a2-49fb-9979-2f240e119499 \
-H 'X-API-KEY: your-access-key-here'
  • {
  "message": "Unauthorized"
}

  • 404 Not Found - Keep Polling

  • curl -X get https://CloudLinkApi/poll/terminalresponse/e02f7fbe-f3a2-49fb-9979-2f240e119499 \
-H 'X-API-KEY: your-access-key-here'

  • This response returns an empty body. The 404 status code indicates the terminal response is pending.

  • 408 Request Timeout - TTL Expired

  • curl -X get https://CloudLinkApi/poll/terminalresponse/e02f7fbe-f3a2-49fb-9979-2f240e119499 \
-H 'X-API-KEY: your-access-key-here'

  • This response returns an empty body. The 408 status code indicates the response queue has expired.

  • 429 Poll Terminal Response - Too Many Requests

  • curl -X get https://CloudLinkApi/poll/terminalresponse/e02f7fbe-f3a2-49fb-9979-2f240e119499 \
-H 'X-API-KEY: your-access-key-here'
  • {
  "message": "Too Many Requests"
}

  • 500 Poll Terminal Response - Server Error

  • curl -X get https://CloudLinkApi/poll/terminalresponse/e02f7fbe-f3a2-49fb-9979-2f240e119499 \
-H 'X-API-KEY: your-access-key-here'
  • {
  "message": "Server Error"
}
In this section: