Poll - Sale
Send a request using the poll method to display a sale on a PAX POS device.
This endpoint allows you to initiate a sale transaction on a payment device using polling. The terminal will display the sale amount and wait for the cardholder to complete the transaction.
Flow:
Send sale request to terminal with pollId.
Terminal displays sale amount and processes payment.
Poll the /poll/terminalresponse/{pollId} endpoint to retrieve the response
Response: Use the returned pollId to poll the terminalresponse endpoint until the response is available. The response will contain the transaction result with eventType "SALE_COMPLETED".
Rate Limiting: The polling endpoint is rate-limited to one call per second per pollId.
Upon receiving the request, the CloudLink API forwards it to the terminal, which immediately registers a SALE_RECEIVED event. Once the cardholder presents their card and the terminal processes the payment, it triggers a final SALE_COMPLETED event. The client can retrieve these events by continuously polling the /poll/terminalresponse/{pollId} endpoint until the terminal response is available.
amount
The amount represented with two minor units, e.g. 12 EUR is 1200.
disablePrinting
Indicates if to print a receipt.
referenceId
Optional reference from merchants
description
Transaction description printed on receipt.
tipAmount
Tip in minor units (e.g., 500 = 5.00).
language
The language that the PAX POS will use to display information on the device. One of the following:
en_GB
ar_EG
da_DK
de_DE
es_ES
fi_FI
fr_FR
hi_IN
is_IS
it_IT
nb_NO
nl_NL
pl_PL
pt_PT
ru_RU
sl_SI
sv_SE
zh_CN
voucherCode
A Mastercard voucher code is a unique alphanumeric code that can be used to redeem a specific value or discount on purchases made with a Mastercard, typically provided as part of a promotion or reward program.
whitelistAids
Specify the AIDs that are allowed to be used in the transaction, terminal config needs a predefined list of AIDs to be able to use this feature.
whitelistBins
Specify the BINs that are allowed to be used in the transaction. Terminal config needs a predefined list of BINs to be able to use this feature.
pollId
The id used to poll after a terminal response.
deviceToken
The token of a PAX POS device.
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.
correlationId
An ID provided by the caller. Returned in the callback for message matching. In a cancel request, use the value from the sale/refund that is being canceled.
timeToLive
The maximum time, in seconds, for a request to reach the physical terminal. The default value is 5 seconds.
type
Example: https://tools.ietf.org/html/rfc7231#section-6.5.1
title
Bad Request
status
400
detail
DeviceId not registered
message
Unauthorized
message
Server Error
/poll/sale
202 Accepted Poll Sale
curl -X post https://CloudLinkApi/poll/sale -H 'X-API-KEY: your-access-key-here' -d ' { "amount": "100", "tipAmount": "500", "description": "Coffee Shop Sale", "disablePrinting": true, "referenceId": "merchant-ref-number-abc123", "language": "en_GB", "voucherCode": "200001", "whitelistAids": [ "AIDNAME1", "AIDNAME2" ], "whitelistBins": [ "BIN1", "BIN2" ], "pollId": "e855e0cf-a026-4614-9dcb-58814455b6a4", "terminalId": "12345678", "deviceToken": "b16526c3447ba6cea4818d", "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda", "timeToLive": 5, "terminalId": null } '{ "message": "Accepted" }
400 Bad Request
curl -X post https://CloudLinkApi/poll/sale -H 'X-API-KEY: your-access-key-here' -d ' { "amount": "100", "tipAmount": "500", "description": "Coffee Shop Sale", "disablePrinting": true, "referenceId": "merchant-ref-number-abc123", "language": "en_GB", "voucherCode": "200001", "whitelistAids": [ "AIDNAME1", "AIDNAME2" ], "whitelistBins": [ "BIN1", "BIN2" ], "pollId": "e855e0cf-a026-4614-9dcb-58814455b6a4", "terminalId": "12345678", "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 Sale
curl -X post https://CloudLinkApi/poll/sale -H 'X-API-KEY: your-access-key-here' -d ' { "amount": "100", "tipAmount": "500", "description": "Coffee Shop Sale", "disablePrinting": true, "referenceId": "merchant-ref-number-abc123", "language": "en_GB", "voucherCode": "200001", "whitelistAids": [ "AIDNAME1", "AIDNAME2" ], "whitelistBins": [ "BIN1", "BIN2" ], "pollId": "e855e0cf-a026-4614-9dcb-58814455b6a4", "terminalId": "12345678", "deviceToken": "b16526c3447ba6cea4818d", "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda", "timeToLive": 5, "terminalId": null } '{ "message": "Unauthorized" }
500 Server Error
curl -X post https://CloudLinkApi/poll/sale -H 'X-API-KEY: your-access-key-here' -d ' { "amount": "100", "tipAmount": "500", "description": "Coffee Shop Sale", "disablePrinting": true, "referenceId": "merchant-ref-number-abc123", "language": "en_GB", "voucherCode": "200001", "whitelistAids": [ "AIDNAME1", "AIDNAME2" ], "whitelistBins": [ "BIN1", "BIN2" ], "pollId": "e855e0cf-a026-4614-9dcb-58814455b6a4", "terminalId": "12345678", "deviceToken": "b16526c3447ba6cea4818d", "correlationId": "5d1d4ea-8229-44d7-b517-26a5ae6c2fda", "timeToLive": 5, "terminalId": null } '{ "message": "Server Error" }