Inquiry

Cortina DQR uses the Inquiry to inquire the approval status of a Transaction ID. This call will include the transaction’s final amount and the transaction ID generated in the GenerateQR call.
An “Approved” response this call will usually attempt to vend/release the product.
A “Decline” will terminate the transaction and a “Pending” response will trigger a subsequent Inquiry request after a predefined time. The Cortina payment provider shall validate the information and respond with the Dynamic QR information to be displayed on the Nayax device accordingly.

This command is essential for the duration of the authorization process.

Request

Nayax's servers send a POST request to your configured Inquiryendpoint, which would be of the following format:

(customer's URL)/Cortina/DynamicQR/Inquiry

The payload includes the full result of the card scan operation:

{
  "BasicInfo": {
    "TransactionId": "236584335969834429321847829253667359",
    "Amount": 0.1,
    "Currency": "ILS",
    "SiteId": 1,
    "MachineAuTime": "230221101008"
  },
  "Products": [
    {
      "Code": 11,
      "Name": "Stella",
      "Price": 0.1,
      "UnitOfMeasurement": "Unit",
      "Measurement": 1
    }
  ],
  "DeviceInfo": {
    "Id": 0,
    "HwSerial": "0434324119376524",
    "FWVersion": "4.0.0.12-RC1 - Sep 22 2020",
    "Type": "ONYX"
  },
  "MachineInfo": {
    "Id": 869761713,
    "Name": "TestPayDynamicQR V2",
    "TerminalId": "987654321",
    "DecimalPlace": 2,
    "Offset": "2.00",
    "CountryCode": "US",
    "CountryISOCode": "USA",
    "Country": "UNITED STATES",
    "City": "Abbeville",
    "Address": "TestPayDynamicQR V2",
    "ZipCode": "1223311"
  },
  "ActorInfo": {
    "Id": 2001505522,
    "Name": "TanyaT_OP",
    "MerchantId": "123456789",
    "CountryCode": "US"
  },
  "CustomData": {
    "Actor": "",
    "Machine": {
      "dynamic_qr_channels_rec_ids": "8,19"
    }
  },
  "PaymentInfo": {
    "SrvTranId": "236584335969834429321847829253667359",
    "AuthAmount": 0.1,
    "SettAmount": 0,
    "RRN": "111111",
    "IsGatewayTimeout": false
  },
  "Polling": {
    "IsLastPolling": false,
    "PollingAttemptCounter": 30
  }
}

Request Parameters

The following table describes the parameters included in the request body:

Field	Type	Description
Transaction Identifiers & References
`TransactionId`	String(36)	The unique identifier for this transaction. Echoes the encrypted ID from `/StartSession` if used. Otherwise, the Nayax Engine generates this value.
`NayaxTransactionId`	Int(64)	The Nayax internal unique ID for the transaction, echoed in further requests.
`SrvTranId`	String	The Integrator's internal transaction ID. Conditional: Required if `/StartSession` was not used. If used, it should be empty or echo the Transaction ID.
`RRN`	String	Reference Retrieval Number (RRN). Recommended to be visible to the consumer/card holder for support.
`AuthCode`	String(40)	External Authorization Code (usually from the Card Issuer's bank).
`Token`	String(256)	A unique token for the transaction. For Nayax internal use only.
`TraceNumber`	String	Trace number. For Nayax internal use only.
`AuthSource`	String(5)	For Nayax internal use only.
Financial & Currency Details
`Amount`	Double	The payment amount (Decimal with max 3 digits for cents). Example: 1 cent = `0.01`. Note: Currencies with no decimal places are still represented as a double (e.g., 234 JYN = `234.0`).
`AuthAmount`	Double	The original amount requested in the `/Authorization` request. Conditional on `/Authorization` response.
`SettAmount`	Double	The original amount requested in the `/Settlement` or `/Sale` process. Irrelevant for Authorization.
`CurrencyCode`	String(3)	Currency code in ISO 4217 Alpha-3 format.
`CurrencyNumeric`	String(3)	Currency code in ISO 4217 Numeric-3 format.
Time & System Status
`AuthDateTime`	String	The date and time the `/Authorization` took place. Format:`ddMMyyHHmmss`.
`SettDateTime`	Double	The Settlement Date/Time. Irrelevant for the Authorization command.
`IsGatewayTimeout`	Bool	Indicates if a gateway timeout occurred (valid in the response).
`IsLastPolling`	Bool	Flag indicating the last polling attempt.
`PollingAttemptCounter`	Int(32)	The current polling attempt number.
Machine & Location Details
`SiteId`	Int(16)	Region of the Nayax server.
`HwSerial`	String	Nayax Device Hardware serial number.
`FWVersion`	String	Device Firmware version.
`Type`	String	Nayax Device Type.
`Id`	Int(64)	Machine entity unique ID.
`Name`	String(255)	Machine Name.
`TerminalId`	String(255)	Terminal identifier. Contact Nayax TPOC to define.
`DecimalPlace`	Int(64)	Decimal point location for amounts.
`Offset`	String(255)	UTC timezone offset.
`GroupId`	String	For Nayax internal use only.
`OperatorId`	String(255)	Merchant ID (String format).
`ZipCode`	String(255)	Machine Zip Code.
Country & Actor Geo Details
`Name`	String	Country Full Name.
`NumericCode`	String(3)	ISO-3166-1 Numeric-3 code.
`Alpha2Code`	String(2)	ISO-3166-1 Alpha-2 code.
`Alpha3Code`	String(3)	ISO-3166-1 Alpha-3 code.
`Id`	Int(64)	Actor ID.
`Name`	String(255)	Direct Merchant name.
`OperatorId`	Int(64)	Merchant operator ID (Integer format).
`OperatorName`	String	Merchant operator name.
`MerchantId`	Int(64)	Merchant ID. Contact Nayax TPOC to define.
Product & Item Details
`Code`	Int(16)	Code of the selected item.
`CatalogProductId`	String(100)	External unique identifier of the selected item (the product catalog number).
`Namme`	String(255)	Product name.
`Price`	Double	The original Product Price in the machine's currency. Note: The transaction amount is the billing price after adjustments.
`UnitOfMeasurement`	String(64)	Product's unit of measurement (e.g., 'unit' or 'Liter').
`Measurement`	Double	Product's quantity in the unit of measurement.
`Group`	String(255)	Product's group name.
`ProductGroupId`	String(255)	Product's group code.
`PulseLineNumber`	Int(32)	Used to support remote vend capability via pulse. Must be a positive integer $(\ge 0)$.
Custom Data (JSON Strings)
`DirectActor`	String	Direct actor custom data (String in JSON format).
`Operator`	String	Operator custom data (String in JSON format).
`Distributor`	String	Distributor custom data (String in JSON format).
`Actor`	String	Actor custom data (String in JSON format).
`Machine`	String	Machine custom data (String in JSON format).
`AdditionalData`	String	General custom data string in JSON format.

Response

The InquiryResponse that the customer's payment method would send to Nayax's servers.

Usually the response would be either "Approved" or "Declined" with code 993 which means "pending"- meaning the payment provider is still working on deciding on whether or not to approve the consumer (pending "Approved" or "Declined" response).
In case of "pending" response, it will lead to Nayax's servers to keep polling until either a final response have been received ("Approved"/Declined") or it reaches the limit as configured in Nayax Core.

The payload should look as follows:

{
  "Status": {
    "Verdict": "Approved",
    "Code": 0,
    "StatusMessage": "Cortina V2 Stub Tester"
  },
  "PaymentInfo": {
    "AuthCode": "333333",
    "AuthAmount": 0.1,
    "SettAmount": 0.1,
    "Token": "Cortina V2 Stub Tester Token",
    "AuthDateTime": "230221101008",
    "SettDateTime": "230221101009",
    "TraceNumber": "4444",
    "AuthSource": "555555",
    "AdditionalData": ""
  }
}

{
  "Status": {
    "Verdict": "Declined",
    "Code": 993,
    "StatusMessage": "Pending"
  },
  "PaymentInfo": {
    "AuthCode": "333333",
    "AuthAmount": 0.1,
    "SettAmount": 0.1,
    "Token": "Cortina V2 Stub Tester Token",
    "AuthDateTime": "230221101008",
    "SettDateTime": "230221101009",
    "TraceNumber": "4444",
    "AuthSource": "555555",
    "AdditionalData": ""
  }
}

Response Parameters

The following table describes the fields returned in the API response:

Field	Type	Description
Transaction Status & Error Codes
`Verdict`	String	The final status of the request. Must be one of the constant string values: `Approved` `Declined`
`Code`	Int(32)	The Decline Code. Conditional—only present if `Verdict` is 'Declined'. Valid decline codes include: 1: Insufficient funds 5: Suspected Fraud 6: General system failure 7: Invalid amount 8 / 998: Format/parsing error or Validation error 992: Timeout exception 997: Missing mandatory parameters 999: General exception 993: Pending (relevant only for Inquiry) See full list for other status and technical errors.
`StatusMessage`	String(255)	A free text field containing the transaction status message or additional varying data regarding the outcome.
`CustomDeclineCode`	String	Used for specifying a custom decline code (e.g., related to Soft Decline or Switch Interface). May reflect the acquirer's response code.
Financial & Time Details
`AuthAmount`	Double	The original amount requested in the `/Authorization` Request.
`SettAmount`	Double	The original amount requested in the `/Settlement` or `/Sale` process. Irrelevant for the Authorization command.
`AuthDateTime`	String	The date and time the `/Authorization` took place. Format:`ddMMyyHHmmss`.
`SettDateTime`	Double	The Settlement Date/Time. Irrelevant for the Authorization command.
Transaction Identifiers & References
`SrvTranId`	String	The Integrator's internal transaction ID. Conditional: Required if `/StartSession` was not used. If used, it should be empty or echo the Transaction ID.
`AuthCode`	String(40)	External Authorization Code (usually from the Card Issuer's bank).
`RRN`	String	Reference Retrieval Number (RRN). Highly recommended to be visible to the consumer/card holder for support.
`Token`	String(256)	A unique token for the transaction. For Nayax internal use only.
`TraceNumber`	String	Trace number. For Nayax internal use only.
`AuthSource`	String(5)	For Nayax internal use only.
`InitiateTranReference`	Int(64)	Conditional: Reflects the original Nayax Transaction ID for prepaid loyalty card re-attempts.
System & External Data
`AdditionalData`	String	Additional data string in JSON format. Contact Nayax TPOC to define.
`IsGatewayTimeout`	Bool	Indicates if a gateway timeout occurred (valid in the response).
`ProviderExternalData`	String	External data from the provider in JSON format string.
`IsRevalueCard`	Bool	Indication if card is allowed revalue.