Skip to main content

​
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: 
{
  "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:
FieldTypeDescription
User & Security Identifiers
AppUserIDString(40)The consumer’s user ID on the 3rd party’s app.
TransactionIdString(40)The unique identifier for the transaction.
  • Will be echoed in all further requests and responses.
  • Minimum length of 8 characters.
SecretTokenString(64)The unique secret key for your system, provided by Nayax in advance. Must be kept secret.
BalanceDoubleThe balance of the user’s account. Decimal value (max 3 digits for cents).
Machine Identification (One is Required)
TerminalIdString(255)The Unique Identifier for the vending machine (HW-Serial of the device).
  • Conditional: Must be sent if UniQR is not sent.
UniQRStringThe 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 ProductsInt(16)The Code of the selected item.
  • Conditional: Mandatory if the machine is not a Pulse machine.
PulseLineNumber inside ProductsInt(32)The pulse line number for remote vend capability.
  • Conditional: Mandatory if the machine is a Pulse machine.
  • Must be a positive integer (≥0\ge 0).
Name inside ProductsString(255)The Product name as defined in the Nayax back office.
Price inside ProductsDoubleThe 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 ProductsString(64)Product’s unit of measurement (e.g., ‘unit’ or ‘Liter’).

​
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:
FieldTypeDescription
Transaction Status & Error Codes
Verdict inside StatusStringThe constant string representing the final status of the request:
  • Approved
  • Declined
Code inside StatusInt(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 StatusString(255)A free text field containing the transaction status message or additional varying data regarding the outcome.
CustomDeclineCode inside StatusStringUsed for specifying a custom decline code (e.g., related to Soft Decline or Switch Interface). May reflect the acquirer’s response code.