query

The query method allows the client application to poll the terminal for the current status of a specific transaction using its requestId or transactionId. This serves as a critical safety mechanism for handling network timeouts or application crashes, ensuring the POS and the terminal remain in sync regarding the payment outcome. Use this method to:

Recover transaction states by checking the final outcome if the original response was lost due to a connection drop.
Verify the current status of a transaction—such as pending, authorized, or declined—without re-triggering the payment logic.
Retrieve transaction metadata for local logging, auditing, and reconciliation support.

Requests

To query a transaction, you must provide the identifier associated with the original request. The following example shows a typical request:

{
"command": "query",
"requestId": "req-006",
"data": {
"filter": "AUTHORIZED"
}
}

Parameter definitions

The table below describes the parameters available for this request:

Field	Type	Required	Description
command	`string`	Yes	Always `query` for this request type.
requestId	`string`	Yes	A unique identifier for the request, returned in the response.
filter	`string`	No	Filter by status: `AUTHORIZED`, `ALL`, `SETTLED`, `FAILED`, or `EXPIRED`.
transactionId	`string`	No	Specific ID to query a single transaction.
fromDate	`string`	No	Start range for the query (ISO 8601).
toDate	`string`	No	End range for the query (ISO 8601).

Responses

The terminal returns the current known state of the transaction. If the transaction is still in progress, the response will reflect its current phase. The following example shows a typical response:

{
"requestId": "req-006",
"data": {
"transactions": [
{
"transactionId": "TXN-20260113-003000",
"state": "AUTHORIZED",
"amount": 50000,
"timeStamp": "2026-01-13T15:00:30Z"
}
]
}
}

Response parameters

The data object will contain the most recent information available for that specific request:

Field	Type	Description
requestId	`string`	Matches the `requestId` sent in the original request.
transactions	`array`	A list of transaction objects matching the query.
transactionId	`string`	The unique identifier for the transaction.
state	`string`	The current status of the transaction (e.g., `AUTHORIZED`, `SETTLED`).
amount	`number`	The authorized amount if `state` is `AUTHORIZED`; otherwise, the settled amount.
timeStamp	`string`	The authorization creation time in Nayax servers (ISO 8601).

Marshall Pro Guides

Payment Flows

Messaging Protocol

Methods

FAQ

Requests

Parameter definitions

Responses

Response parameters

​Requests

​Parameter definitions

​Responses

​Response parameters

Requests

Parameter definitions

Responses

Response parameters