Settlement

Cortina Prepaid uses the Settlementcommand to notify the integrator about the result of a settlement process on the device's end (meaning a product has been vended) in order to initiate the settlement 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 Settlementendpoint, which would be of the following format:

(customer's URL)/Cortina/PrePaid/Settlement

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,
    "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"
    },
    "CardHolderName": "Test Card Holder"
  },
  "Products": [
    {
      "Code": 11,
      "Name": "Stella",
      "Price": 0.1,
      "UnitOfMeasurement": "USD",
      "Measurement": false
    },
    {
      "Code": 12,
      "Name": "expensiveSprite",
      "Price": 6,
      "UnitOfMeasurement": "USD",
      "Measurement": false
    }
  ],
  "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
  },
  "SecondaryDescription": "string"
}

Request Parameters

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

Reference Fields

Field	Type	Description
Transaction Identifiers & Status
`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 subsequent 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 from the request.
`RRN`	`String`	Reference Retrieval Number (RRN). Used as the external transaction ID for third parties (e.g., Card Schemes). Recommended to be visible to the consumer/cardholder.
`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.
Financial Details & Amounts
`Amount`	`Double`	The payment amount. Decimal value (max 3 digits for cents). Currencies without decimals (e.g., JYN) are still represented as a double (e.g., `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 the Authorization command.
`CurrencyCode`	`String(3)`	The currency code in ISO 4217 Alpha-3 format (e.g., USD, EUR).
`CurrencyNumeric`	`String(3)`	The currency code in ISO 4217 Numeric-3 format.
`DecimalPlace`	`Int(64)`	The decimal point location for amounts on this machine. Example: `2` means amounts like 123.45. Example: `0` means amounts like 12345 (integer representation).
`AuthCode`	`String(40)`	The External Authorization Code (usually from the Card Issuer).
Timestamps & Flags
`MachineAuTime`	`String`	The Machine Authorization Timestamp.
`TimeoutMS`	`Int(32)`	Nayax Server Timeout configuration in milliseconds.
`Offset`	`String(255)`	UTC timezone offset for the machine's location.
`AuthDateTime`	`String`	The date and time the `/Authorization` took place. Format:`ddMMyyHHmmss`.
`SettDateTime`	`Double`	The Settlement Date/Time. Relevant only for Settlement-related commands. Irrelevant for Authorization.
`IsGatewayTimeout`	`Bool`	Indicates if a gateway timeout occurred (valid in the response).
Card & Payment Details
`CardNumber`	`String`	Card details provided based on transaction type: Full Track 2 for card-present Authorizations/Sales. Card PAN only for other transaction types (e.g., Refund, Settlement).
`EntryMode`	`String(4)`	How the card details were read: MCR: Magstripe (Swipe) CON: Contact Chip (Insert) CLS: Contactless Chip (Tap) NFC: Phone Tap 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.
`IDNumber`	`String`	Cardholder ID/identification number.
`RandomNumber`	`String`	Further information is unavailable.
`PrimaryId`	`String`	Primary Brand ID (e.g., Visa, Mastercard).
`PrimaryDescription`	`String`	Primary Brand Description.
`SecondaryId`	`String`	Secondary Brand ID (if applicable).
`CardHolderName`	`String`	Name of the cardholder.
Product/Item Details
`IsProductSelected`	`Bool`	Indicates if the product was pre-selected before the payment process.
`Code`	`Int(16)`	The code of the selected item as defined in Nayax's back office or the vending machine.
`CatalogProductId`	`String(100)`	The external unique identifier of the selected item (the product catalog number).
`Name`	`String(255)`	The Product name as defined in the Nayax back office.
`Price`	`Double`	The original Product Price in the machine's currency. Note: `Amount` is the final billing price after adjustments.
`UnitOfMeasurement`	`String(64)`	Product's unit of measurement (e.g., 'unit' or 'Liter').
`Measurement`	`Double`	Product's quantity in the specified unit of measurement.
`Group`	`String(255)`	Product's group name as defined in the product map.
`ProductGroupId`	`String(255)`	Product's group code as defined 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 & Device Information
`HwSerial`	`String`	Nayax Device Hardware serial number.
`FWVersion`	`String`	Device Firmware Version.
`Type`	`String`	Nayax Device Type.
`Id`	`Int(64)`	Machine Entity Unique ID allocated in Nayax's back office.
`Name`	`String(255)`	Machine Name as defined in Nayax's back office.
`TerminalId`	`String(255)`	Terminal identifier as defined in Nayax's back office.
Machine Location
`SiteId`	`Int(16)`	Region of the Nayax server hosting the machine data.
`Region`	`String(255)`	Machine Region as defined in Nayax's back office.
`City`	`String(255)`	Machine City as defined in Nayax's back office.
`ZipCode`	`String(255)`	Machine Zip Code as defined in Nayax's back office.
`Latitude`	`String`	Machine Location Latitude.
`Longitude`	`String`	Machine Location Longitude.
Actor (Merchant/Operator) Details
`Id`	`Int(64)`	Actor ID (Direct Merchant/Operator) defined in Nayax's back office.
`Name`	`String(255)`	Direct Merchant Name as defined in Nayax's back office.
`OperatorId`	`String(255)`	Merchant ID (Operator ID - String version) as defined in Nayax's back office.
`OperatorId`	`Int(64)`	Merchant Operator ID (integer version).
`OperatorName`	`String`	Merchant Operator Name.
`MerchantId`	`Int(64)`	Merchant ID as defined in Nayax's back office.
`DynamicURL`	`String`	Actor-level URL configuration.
`State`	`String`	Actor geo state code.
`City`	`String(255)`	Actor geo city.
`CountryCode`	`String`	Actor geo country code (ISO-3).
`ZipCode`	`String(255)`	Actor geo zip code.
`Address`	`String(255)`	Actor geo address.
Country Information (ISO 3166-1)
`Name`	`String`	Country Full Name.
`NumericCode`	`String(3)`	Country code in ISO 3166-1 Numeric-3 format.
`Alpha2Code`	`String(2)`	Country code in ISO 3166-1 Alpha-2 format.
`Alpha3Code`	`String(3)`	Country code in ISO 3166-1 Alpha-3 format.
`Intra`	`String`	The Intra Region (e.g., 'European Union') used for geographical diversification across countries.
Custom Data (JSON Strings)
`GroupId`	`String`	For Nayax internal use only.
`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 Settlement 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"
  },
  "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
Transaction Status & Errors
`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 8 / 998: Format/parsing error 992: Timeout exception 997: Missing mandatory parameters 999: General exception
`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. Often related to Soft Decline or interface switching. May reflect the acquirer's response code or custom data.
Loyalty & Credit Information
`RegularCreditType`	`Int(32)`	Defines the unit of measure for `RegularCredit` (Enum values): 0: Credit is counted in transactions (count). 1: Credit is counted as an amount (currency).
`RegularCredit`	`Double`	The regular credit value (amount or transaction count) based on the `RegularCreditType`. Uses Decimal place 2.
`RevalueCredit`	`Int(32)`	The revalue credit amount. Only present if the associated card is configured as revalue-able. Uses Decimal place 2.