Request Merchant Config

This endpoint allows you to retrieve merchant configuration information from a payment device. The terminal will respond with available merchants, currencies, and terminal details.

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

Flow:

Send request to terminal.
Terminal processes request.
Terminal sends response via webhook to the specified callback URL.

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 Body Parameters

- callbackUrl
- The URL that CloudLinkApi will use to return the merchant configuration to the caller.

- deviceToken
- The token of a PAX POS device.

- correlationId
- An ID provided by the caller. Returned in the callback for message matching.

- terminalId
- If terminal has more than one merchant, this field is used to identify the merchant. To get a list of merchants, use the requestMerchantConfig request

- timeToLive
- The maximum time, in seconds, for a request to reach the physical terminal. The default value is 5 seconds.

202 Accepted Response

400 Error Response

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

- title
- Bad Request

- status
- 400

- detail
- DeviceId not registered

401 Error Response

- message
- Unauthorized

500 Error Response

- message
- Server Error

/requestMerchantConfig

202 Accepted Request Merchant Config

curl -X post https://CloudLinkApi/requestMerchantConfig \
-H 'X-API-KEY: your-access-key-here' \
-d '
{
  "callbackUrl": "http://example.com/webhook-endpoint",
  "deviceToken": "b16526c3447ba6cea4818d",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "timeToLive": 5,
  "terminalId": null 

}
'

```
{
  "message": "Accepted"	
}
```

400 Bad Request

curl -X post https://CloudLinkApi/requestMerchantConfig \
-H 'X-API-KEY: your-access-key-here' \
-d '
{
  "callbackUrl": "http://example.com/webhook-endpoint",
  "deviceToken": "b16526c3447ba6cea4818d",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "timeToLive": 5,
  "terminalId": null  
}
'

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "DeviceId not registered"
}

401 Unauthorized

curl -X post https://CloudLinkApi/requestMerchantConfig \
-H 'X-API-KEY: your-access-key-here' \
-d '
{
  "callbackUrl": "http://example.com/webhook-endpoint",
  "deviceToken": "b16526c3447ba6cea4818d",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "timeToLive": 5,
  "terminalId": null 
}
'

```
{
  "message": "Unauthorized"
}
```

500 Server Error

curl -X post https://CloudLinkApi/requestMerchantConfig \
-H 'X-API-KEY: your-access-key-here' \
-d '
{
  "callbackUrl": "http://example.com/webhook-endpoint",
  "deviceToken": "b16526c3447ba6cea4818d",
  "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda",
  "timeToLive": 5,
  "terminalId": null 
}
'

```
{
  "message": "Server Error"
}
```

In this section:

Documentation