Skip to main content

Documentation

Poll - Terminal Config Response

Check via the poll method if the terminal has responded to a merchant configuration 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 returned a merchant configuration. 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).

  • Responses have a TTL: If you do not poll within the timeout window, the response expires. You will need to send a new /poll/requestMerchantConfig request to try again.

  • Merchant configuration requests do not trigger a SALE_RECEIVEDevent. The terminal immediately processes the request and returns the list of merchants via a MERCHANT_CONFIG callback.

Parameters
Request Header Parameters
Request Path Parameters

    • pollId

    • The pollId that was provided in the initial requestMerchantConfig request.

200 OK Response

    • eventType

    • The event type returned by the terminal (e.g., MERCHANT_CONFIG).

    • correlationId

    • The correlation ID provided in the original request.

    • merchantConfig

    • Array of merchant configuration items available on the terminal. Each item represents one merchant/currency combination.

400 Error Response

    • type

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

    • title

    • Bad Request

    • status

    • 400

    • detail

    • Invalid pollId or malformed request

401 Error Response

    • message

    • Unauthorized

404 Not Found Response

    • message

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

408 Request Timeout Response

    • message

    • The response has expired in the queue. Stop polling.

429 Error Response

    • message

    • Too many requests

500 Error Response

    • message

    • Server Error

  • /poll/terminalConfigResponse/{pollId}

  • 200 OK - Merchant Config Available

  • curl -X get https://CloudLinkApi/poll/terminalConfigResponse/94eb1c2a-661d-45f5-adff-cb14af787a29 \
-H 'X-API-KEY: your-access-key-here'
  • {
  "eventType": "MERCHANT_CONFIG",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "merchantConfig": [
    {
      "currencyCode": "EUR",
      "merchantId": "12345678",
      "merchantName": "Sample Store EUR",
      "terminalId": "TERM001"
    },
    {
      "currencyCode": "USD",
      "merchantId": "87654321",
      "merchantName": "Sample Store USD",
      "terminalId": "TERM001"
    },
    {
      "currencyCode": "GBP",
      "merchantId": "11223344",
      "merchantName": "Sample Store GBP",
      "terminalId": "TERM001"
    }
  ]
}

  • 401 Unauthorized - Invalid API key

  • curl -X get https://CloudLinkApi/poll/terminalConfigResponse/94eb1c2a-661d-45f5-adff-cb14af787a29 \
-H 'X-API-KEY: your-access-key-here'
  • {
  "message": "Unauthorized"
}

  • 404 Response not yet available, continue polling

  • curl -X get https://CloudLinkApi/poll/terminalConfigResponse/94eb1c2a-661d-45f5-adff-cb14af787a29 \
-H 'X-API-KEY: your-access-key-here'
  • {
"message": "The terminal has not reported back yet. This is expected behavior. Keep polling."
}

  • 408 Response has timed out

  • curl -X get https://CloudLinkApi/poll/terminalConfigResponse/94eb1c2a-661d-45f5-adff-cb14af787a29 \
-H 'X-API-KEY: your-access-key-here'
  • {
 "message": "The response has expired in the queue. Stop polling."
}

  • 429 Rate limit exceeded

  • curl -X get https://CloudLinkApi/poll/terminalConfigResponse/94eb1c2a-661d-45f5-adff-cb14af787a29 \
-H 'X-API-KEY: your-access-key-here'
  • {
 "message": "Too many requests."
}

  • 500 Server Error

  • curl -X get https://CloudLinkApi/poll/terminalConfigResponse/94eb1c2a-661d-45f5-adff-cb14af787a29 \
-H 'X-API-KEY: your-access-key-here'
  • {
  "message": "Server Error"
}
In this section: