Start

Request

The Cortina payment method would send a Start command to Nayax’s servers in order to notify them about starting a transaction. The call would be of the following format:

https://lynx.nayax.com/payment/v2/transactions/cortina/(payment method's name)/start

The payload includes the following details:

JSON-TerminalID

{
  "AppUserID": "19",
	"TerminalId": "0456789456789456",
  "TransactionId": "123456789qwertyuioasdfghjkl",
  "SecretToken": "mrV3U3nsgGFrE3w5-wnBo_WCLPce-pZ1awRvTVTkungMIKThTVbj_fiXdfoGclhn0"
}

Request Parameters

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

Field	Type	Description
User & Security Identifiers
AppUserID	String(40)	The consumer’s user ID on the 3rd party’s app.
TransactionId	String(40)	The unique identifier for the transaction. Will be echoed in all further requests and responses. Minimum length of 8 characters.
SecretToken	String(64)	The unique secret key for your system, provided by Nayax in advance. Must be kept secret.
Balance	Double	The balance of the user’s account. Decimal value (max 3 digits for cents).
Machine Identification (One is Required)
TerminalId	String(255)	The Unique Identifier for the vending machine (HW-Serial of the device). Conditional: Must be sent if UniQR is not sent.
UniQR	String	The QR code value linked to the machine. Conditional: Must be sent if TerminalId is not sent.
Product Selection (Products Array)
Products Array	***	The array is optional, but if provided, some inner fields are mandatory. Only relevant for the PreSelection flow.
Code inside Products	Int(16)	The Code of the selected item. Conditional: Mandatory if the machine is not a Pulse machine.
PulseLineNumber inside Products	Int(32)	The pulse line number for remote vend capability. Conditional: Mandatory if the machine is a Pulse machine. Must be a positive integer ($\ge 0$).
Name inside Products	String(255)	The Product name as defined in the Nayax back office.
Price inside Products	Double	The original Product price in the machine’s currency. Conditional: Mandatory if the machine does not have a price setup for the product code. Note: The transaction amount is the final billing price after adjustments.
UnitOfMeasurement inside Products	String(64)	Product’s unit of measurement (e.g., ‘unit’ or ‘Liter’).

Remote Vend: Product Selection

The following applies to the PreSelection flow only. To specify which product to vend, include a "code" field inside the "Products" array with the corresponding product index.

Pulse machine code numbering

For Pulse array machines (any Pulse configuration except Pulse Line), the "code" numbering starts from 0.
For example, in case of:

• "Code": 0 → “Ultimate” product
• "Code": 1 → “Superior” product
• "Code": 2 → “Regular” product

If you send a number outside the scope of the virtual machine’s array, our servers will select the first item in the list (Code: 0).

For Pulse 1–6 configurations (Pulse Line), use "PulseLineNumber" instead of "code", and the counting starts from 1 (not 0).

Response

The Start Response that Nayax’s servers would send to the payment method.
The payload should look as follows:

{
  "Status": {
    "Verdict": "Approved",
    "StatusMessage": "Cortina V2 Stub Tester"
  }
}

Response Parameters

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

Field	Type	Description
Transaction Status & Error Codes
Verdict inside Status	String	The constant string representing the final status of the request: Approved Declined
Code inside Status	Int(32)	The Decline Code. Conditional—only present if Verdict is ‘Declined’. Valid 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 See full list for other status and internal errors (e.g., 40, 990, 1011).
StatusMessage inside Status	String(255)	A free text field containing the transaction status message or additional varying data regarding the outcome.
CustomDeclineCode inside Status	String	Used for specifying a custom decline code (e.g., related to Soft Decline or Switch Interface). May reflect the acquirer’s response code.