Sale

Cortina Prepaid uses the Sale command to notify the integrator about the result of a card tap after a product has been selected in order to initiate the authorization process with the Cortina payment provider. This command is essential for proceeding to transaction confirmation or rejection handling.

Request

Nayax’s servers send a POST request to your configured Sale endpoint, which would be of the following format: (customer's URL)/Cortina/PrePaid/Sale The payload includes the full result of the card scan operation:

{
"BasicInfo": {
"TransactionId": 2.3658433596983443e+35,
"NayaxTransactionId": 0,
"Amount": 0.1,
"CurrencyCode": "USD",
"CurrencyNumeric": 376,
"SiteId": 12,
"MachineAuTime": "string",
"TimeoutMS": 15000,
"IsProductSelected": true
},
"DeviceInfo": {
"HwSerial": "string",
"FWVersion": "string",
"Type": "ONYX"
},
"MachineInfo": {
"Id": 869761713,
"Name": "TestPayStaticQR V2",
"TerminalId": 987654321,
"DecimalPlace": 2,
"Offset": 2,
"GroupId": "Beverages",
"OperatorId": 12345,
"Region": "string",
"City": "string",
"ZipCode": 10001,
"Type": "Food",
"Country": {
"Name": "United States of America",
"NumericCode": 840,
"Alpha2Code": "US",
"Alpha3Code": "USA"
},
"GeoLocation": {
"State": "string",
"City": "string",
"CountryCode": "string",
"ZipCode": "string",
"Address": "string",
"Longitude": 34.998819,
"Latitude": 32.8198988
}
},
"ActorInfo": {
"Id": 2001102296,
"Name": "Far East Dev Zone",
"OperatorId": 2000305191,
"OperatorName": "TanyaT_OP",
"MerchantId": 10011,
"Country": {
"Name": "string",
"NumericCode": "string",
"Alpha2Code": "string",
"Alpha3Code": "string"
},
"GeoLocation": {
"State": "string",
"City": "string",
"CountryCode": "string",
"ZipCode": "string",
"Address": "string",
"Longitude": 34.998819,
"Latitude": 32.8198988
}
},
"CustomData": {
"DirectActor": 12312312,
"Operator": 123121434134,
"Distributor": "superDistributor",
"Actor": 12312312,
"Machine": 131231348
},
"CardData": {
"CardNumber": "string",
"EntryMode": "string",
"ExpYear": "string",
"ExpMonth": "string",
"EMVData": "string",
"IDNumber": "string",
"RandomNumber": "string",
"BrandInfo": {
"PrimaryId": "string",
"PrimaryDescription": "string",
"SecondaryId": "string",
"SecondaryDescription": "string"
},
"CardHolderName": "Test Card Holder"
},
"PaymentInfo": {
"SrvTranId": 2.3658433596983443e+35,
"AuthCode": 333333,
"AuthAmount": 0.1,
"SettAmount": 0.1,
"RRN": 111111,
"Token": "string",
"AuthDateTime": 230221101008,
"SettDateTime": 230221101009,
"TraceNumber": 4444,
"AuthSource": 555555,
"AdditionalData": "string",
"IsGatewayTimeout": true
},
"Products": [
{
"Code": 11,
"Name": "Stella",
"Price": 0.1,
"UnitOfMeasurement": "USD",
"Measurement": false
},
{
"Code": 12,
"Name": "expensiveSprite",
"Price": 6,
"UnitOfMeasurement": "USD",
"Measurement": false
}
]
}

Request Parameters

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

Reference Fields

Field	Type	Description
Transaction Status & Core Identifiers
`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 997: Missing mandatory parameters 999: General exception See full documentation for complete list of codes.
`StatusMessage`	String(255)	A free text field containing the transaction status message or additional varying data regarding the outcome.
`TransactionId`	String(36)	The unique identifier for this transaction. Echoes the encrypted ID from `/StartSession` if used. Otherwise, the Nayax Engine generates the 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: Only mandatory if `/StartSession` was not used. If used, it should be empty or echo the Transaction ID.
`RRN`	String	Reference Retrieval Number. External transaction ID for third parties. Highly recommended to be visible to the consumer/card holder.
`Token`	String(256)	A unique transaction token. For Nayax internal use only.
`TraceNumber`	String	The 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.
Financial Details, Card Information, & Timestamps
`Amount`	Double	The payment amount (Decimal with max 3 digits for cents). Example: 1 cent = `0.01`. Currencies with no decimal places (e.g., JYN) are still represented as a double (e.g., `234.0`).
`AuthAmount`	Double	The original amount requested in the `/Sale`Request. Conditional on `/Sale` Response.
`SettAmount`	Double	The original amount requested in the `/Sale`Request. Conditional on `/Sale` Response.
`AuthCode`	String(40)	External Authorization Code (usually from the Card Issuer’s bank).
`CurrencyCode`	String(3)	Currency code in ISO 4217 Alpha-3 format.
`CurrencyNumeric`	String(3)	Currency code in ISO 4217 Numeric-3 format.
`AuthDateTime`	String	The date and time the `/Sale` took place. Format:`ddMMyyHHmmss`. Conditional on `/Sale` Response.
`SettDateTime`	Double	The Settlement Date/Time. Conditional on `/Sale` Response.
`CardNumber`	String	Card details provided based on transaction type: Full Track 2 for card-present Authorization/Sale. Card PAN only for other transaction types (e.g., Refund, Settlement).
`EntryMode`	String(4)	How the card details were read. Common values: MCR: Magnetic Stripe Read CON: Contact Chip (insert) CLS: Contactless Chip (tap) NFC: Phone/Mobile contactless QR: QR code read
`ExpYear`	String	Card expiration year (YY format). Conditional (only when Interface is 1 or 10).
`ExpMonth`	String	Card expiration month (MM format). Conditional (only when Interface is 1 or 10).
`EMVData`	String	EMV tags data in TLV (Tag-Length-Value) format.
`CVV2`	String	Card Verification Value 2 (CVV2).
`IDNumber`	String	Cardholder ID Number.
`RandomNumber`	String	Further information is unavailable.
`PrimaryId`	String	Primary Brand ID.
`PrimaryDescription`	String	Primary Brand Description.
`SecondaryId`	String	Secondary Brand ID.
`SecondaryDescription`	String	Secondary Brand Description.
`CardHolderName`	String	Card Holder Name.
`IsDebitCard`	Bool	Indication if card is Debit or Prepaid.
`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.
Product & Item Details
`Code`	Int(16)	Code of the selected item as defined in the Nayax back office or vending machine.
`CatalogProductId`	String(100)	External unique identifier of the selected item (the product catalog number).
`Name`	String(255)	Product name as defined in Nayax’s back office.
`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 as existing in the product map.
`ProductGroupId`	String(255)	Product’s group code as existing in the product map.
`PulseLineNumber`	Int(32)	Used to support multiple machines via pulse for remote vend capability. Must be a positive integer $(\ge 0)$ .
Machine & Actor Information
`SiteId`	Int(16)	Region of the Nayax server.
`MachineAuTime`	String	Machine Authorization Timestamp.
`TimeoutMS`	Int(32)	Nayax Server Timeout configuration in milliseconds.
`IsProductSelected`	Bool	Indication if the product was pre-selected.
`PaymentMethodID`	Int(32)	Nayax identifier of the payment provider.
`BillingProviderId`	Int(32)	Nayax identifier of the billing provider.
`AuditNumber`	Int(64)	For Nayax internal use only.
`IsDeferredAuthorization`	Bool	Further information is unavailable.
`AgeLimitation`	Int(16)	Minimum age required to allow the transaction.
`IsSoftDeclineCompletion`	Bool	Further information is unavailable.
`TransitTransactionType`	Int(32)	The Transit Transaction Type (Enum values): 1: Prefunded 2: Realtime Authorization 3: Post-Authorization / Aggregated Transaction 7: Debt Recovery
`DenyListIndication`	Int(32)	Indicates the effect on the consumer’s Deny List status (Enum values): 0: Unknown/no effect 1: Decline causes consumer to be added to the deny list. 2: Approval causes consumer to be removed from the deny list.
`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.
`ExternalId`	String(200)	Machine External ID (Machine number - operator).
`Type`	String(50)	Machine Type.
`TerminalId`	String(255)	Terminal identifier. Contact Nayax TPOC to define.
`DecimalPlace`	Int(64)	Decimal point location for amounts. Example: `2` means amounts like 123.45.
`Offset`	String(255)	UTC timezone offset.
`GroupId`	String	For Nayax internal use only.
`OperatorId`	String(255)	Merchant ID (String format).
`Region`	String(255)	Machine Region.
`City`	String(255)	Machine City.
`ZipCode`	String(255)	Machine Zip Code.
`Name`	String	Country Full Name (for machine location).
`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.
`Intra`	String	The Intra Region (geographical diversification across countries).
`State`	String	Actor geo state code.
`City`	String(255)	Actor geo City.
`CountryCode`	String	Actor geo Country code (ISO3).
`ZipCode`	String(255)	Actor geo Zip code.
`Address`	String(255)	Actor geo Address.
`Latitude`	String	Machine Location Latitude.
`Longitude`	String	Machine Location Longitude.
`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.
`DynamicURL`	String	Actor level URL configuration.
`MCC`	Int(32)	Merchant Category Code (MCC), classifying the business type.
`SubMerchantId`	String(255)	Sub Merchant identifier. Contact Nayax TPOC to define.
`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).
`SoftDecline`	String	Soft Decline custom data (String in JSON format).

Response

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

{
  "Status": {
    "Verdict": "Approved",
    "Code": 0,
    "StatusMessage": "string"
  },
  "PaymentInfo": {
    "SrvTranId": 2.3658433596983443e+35,
    "AuthCode": 333333,
    "AuthAmount": 0.1,
    "SettAmount": 0.1,
    "RRN": 111111,
    "Token": "string",
    "AuthDateTime": 230221101008,
    "SettDateTime": 230221101009,
    "TraceNumber": 4444,
    "AuthSource": 555555,
    "AdditionalData": "string",
    "IsGatewayTimeout": true
  },
  "Balance": {
    "RegularCreditType": 0,
    "RegularCredit": 0,
    "RevalueCredit": 0
  }
}

Response Parameters

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

Reference Fields

Field	Type	Description
`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’. Common codes include: 1: Insufficient funds 5: Suspected Fraud 6: General system failure 7: Invalid amount 992: Timeout exception 997: Missing mandatory parameters 999: General exception 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.
`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)	The External Authorization Code (usually from the Card Issuer’s bank).
`AuthAmount`	Double	The original amount requested in the `/Sale` Request.
`SettAmount`	Double	The original amount requested in the `/Sale` Request.
`RRN`	String	Reference Retrieval Number. External transaction ID for third parties. Highly recommended to be visible to the consumer/card holder.
`Token`	String(256)	A unique token for the transaction. For Nayax internal use only.
`AuthDateTime`	String	The date and time the `/Authorization` took place. Format:`ddMMyyHHmmss`.
`SettDateTime`	Double	The Settlement Date/Time. Irrelevant for the Authorization command.
`TraceNumber`	String	The Trace number. For Nayax internal use only.
`AuthSource`	String(5)	For Nayax internal use only.
`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.
`InitiateTranReference`	Int(64)	Conditional: Reflects the original Nayax Transaction ID for prepaid loyalty card re-attempts.
`IsRevalueCard`	Bool	Indication if card is allowed revalue.

Cortina Guides

API Reference

Request

Request Parameters

Response

Response Parameters

​Request

​Request Parameters

​Response

​Response Parameters

Request

Request Parameters

Response

Response Parameters