Skip to main content

Documentation

Terminal Responses

The customer polls the API with the poll id using the /poll/terminalresponse/{pollId} endpoint. The latest terminal response is delivered in the response.

Contract

The following contract is returned in the response body. All properties are optional, and endpoints must be designed to gracefully handle the addition of new properties without failing. For backward compatibility, properties will never be removed from the contract.

      • {
  "eventType": "NONE",
  "callbackUrl": "string",
  "correlationId": "string",
  "terminalResponse": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

The following properties are expected in the response for transaction-related events (such as SALE_COMPLETED or DISCOUNT_CARD_READ). For backward compatibility, properties will never be removed from the contract.

      • "terminalResponse": {
    "responseCode": "string",
    "result": "string",
    "uti": "string",
    "amount": "string",
    "authorizationCode": "string",
    "approved": "string",
    "transCancelled": "string",
    "cardholderReceipt": "string",
    "merchantReceipt": "string",
    "cardPan": "string",
    "cardType": "string",
    "cardTypeExtra": "string",
    "cardLength": "string",
    "aid": "string",
    "tsi": "string",
    "tvr": "string",
    "cvmr": "string",
    "terminalId": "string",
    "merchantId": "string",
    "stan": "string",
    "retrievalReferenceNumber": "string",
    "softwareVersion": "string",
    "dateTime": "string",
    "latitude": "string",
    "longitude": "string",
    "tipAmount": "string",
    "dccTransaction": "string",
    "dccOriginalAmount": "string",
    "dccCurrency": "string",
    "walletProvider": "string",
    "voided": "string",
    "voucherBenefitCardIssuer": "string",
    "voucherWalletName": "string",
    "voucherBalance": "string",
    "voucherExpirationDate": "string",
    "isSignature": "string",
    "signature": "string",
    "cvmResult": "string",
    "payerAccountReference": "string",
    "processorCorrelationId": "string",
    "productId": "string",
    "productDescription": "string",
    "issuerIdentifier": "string",
    "issuingCountry": "string",
    "issuerRegion": "string",
    "cardholderBillingCurrency": "string",
    "cardUsage": "string",
    "cardCategory": "string",
    "acquirer": "string",
    "transactionSource": "string"
}

The following properties are expected when the eventType is TERMINAL_ERROR. For backward compatibility, properties will never be removed from the contract.

      • "terminalResponse": {
    "errorMessage": "string"
}
Event types

  • NONE - Default/unset state.

  • SALE_RECEIVED - Terminal received the request (sent immediately, before card presentation or transaction processing begins). No action required by the client.

  • SALE_REQUESTED - Sale initiated directly at the terminal device (requires POS confirmation).

  • DISCOUNT_CARD_READ - The terminal has read a discount/loyalty card and has suspended the transaction. The client must respond with a discount action (Update Price or External Result).

  • SALE_COMPLETED - The transaction successfully completed. Polling and receiving this response constitutes the acknowledgment. Do not use the deprecated /poll/confirmation endpoint.

  • SALE_CANCELLED - Cardholder or merchant have cancelled the transaction at the POS device. Final state for a transaction, no further actions available.

  • SALE_VOIDED - The transaction was voided (final state). Sent in response to a void request, or automatically if acknowledgment times out.

  • TERMINAL_BUSY - Terminal is processing another transaction. Exception: if the incoming request has the same referenceId as the current transaction, it is treated as a retry (not busy). Otherwise, retry to check for availability.

  • TERMINAL_ERROR - Terminal encountered an error (e.g., payment core not installed, or merchant configuration update failed such as terminalId not found). No cleanup required on behalf of the client.

  • MERCHANT_CONFIG - Merchant configuration response.

In this section: