Guides
Start typing to search…

Prepaid Card- 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 table below describes all the parameters of the request:

Catergory

Field

Type

Required

Description

BasicInfo

TransactionId

String(36)

Yes

The unique identifier for this transaction.

If /StartSession has been used then this will echo the transaction Id encrypted in 'TranIDCipher'.
If /StartSession was not Used - Nayax Engine shall generate this Value.

NayaxTransactionId

Int(64)

Yes

Nayax Internal Unique identifier for the transaction which will be echoed in further requests.

Amount

Double

Yes

Decimal (max 3 digits for cents)
The amount of the payment Example: 1 cent = 0.01, 20 cents = 0.20

  • Note: Currencies with no Decimal Place shall be represented as double as well.
    Example: 234 JYN = 234.0.

CurrencyCode

String(3)

Yes

Currency according to ISO4217 Attribute format: Alpha-3.

CurrencyNumeric

String(3)

Yes

Currency according to ISO4217 Attribute format: Numeric-3.

SiteId

Int(16)

No

Region of the Nayax server.

MachineAuTime

String

No

Machine Authorization Timestamp

TimeoutMS

Int(32)

No

Nayax Server T/O configuration, in milliseconds

IsProductSelected

Bool

No

indication if the product was pre-selected

DeviceInfo

HwSerial

String

No

Nayax Device Hardware serial number as embedded on the device

FWVersion

String

No

Device Firmware version

Type

String

No

Nayax Device Type

MachineInfo

Id

Int(64)

Yes

Machine entity unique ID allocated in Nayax'S backoffice.

Name

String(255)

Yes

Machine Name as defined in Nayax'S backoffice

TerminalId

String(255)

No

Terminal identifier as defined in Nayax's backoffice.
Contact Nayax TPOC to define.

DecimalPlace

Int(64)

No

Decimal point location for amounts used on this machine.
Example: a value of '2' refers to possible amounts such as 123.45, while a value of '0' refers to amount 12345

Offset

String(255)

No

UTC timezone offset

GroupId

String

No

For Nayax internal use only.

OperatorId

String(255)

No

Merchant ID as defined in Nayax's backoffice

Region

String(255)

No

Region as defined in Nayax's backoffice

City

String(255)

No

Machine city as defined in Nayax's backoffice

ZipCode

String(255)

No

Machine zipcode as defined in Nayax's backoffice

Country inside MachineInfo

Name

String

Yes

Country Full Name

Country inside MachineInfo

NumericCode

String(3)

Yes

ISO-3166-1 format: Numeric-3 code

Country inside MachineInfo

Alpha2Code

String(2)

Yes

ISO-3166-1 format: Alpha-2 code

Country inside MachineInfo

Alpha3Code

String(3)

Yes

ISO-3166-1 format: Alpha-3 code

Country inside MachineInfo

Intra

String

Yes

An Intra Region refers to a geographical diversification across countries within a single 'Intra region'.
E.g. 'France' is country within the 'European Union' Intra Region.

GeoLocation inside MachineInfo

State

String

No

Actor geo state code as defined in Nayax's backoffice

GeoLocation inside MachineInfo

City

String(255)

No

City as defined in Nayax's backoffice

GeoLocation inside MachineInfo

CountryCode

String

No

Country code (ISO3) as defined in Nayax's backoffice

GeoLocation inside MachineInfo

ZipCode

String(255)

No

Zip code as defined in Nayax's backoffice

GeoLocation inside MachineInfo

Address

String(255)

No

Address as defined in Nayax's backoffice

GeoLocation inside MachineInfo

Latitude

String

No

Machine Location Latitude as defined in Nayax's backoffice

GeoLocation inside MachineInfo

Longitude

String

No

Machine Location Longitude as defined in Nayax's backoffice

ActorInfo

Id

Int(64)

Yes

Actor ID as saved as defined in Nayax's backoffice

Name

String(255)

Yes

Direct Merchant name as defined in Nayax's backoffice

OperatorId

Int(64)

No

Merchant operator ID as defined in Nayax's backoffice

OperatorName

String

No

Merchant operator name as defined in Nayax's backoffice

MerchantId

Int(64)

No

Merchant ID as defined in Nayax's backoffice.
Contact Nayax TPOC to define.

DynamicURL

String

No

Actor level URL configuration

Country inside ActorInfo

Name

String

Yes

Country Full Name

Country inside ActorInfo

NumericCode

String(3)

Yes

ISO-3166-1 format: Numeric-3 code

Country inside ActorInfo

Alpha2Code

String(2)

Yes

ISO-3166-1 format: Alpha-2 code

Country inside ActorInfo

Alpha3Code

String(3)

Yes

ISO-3166-1 format: Alpha-3 code

GeoLocation inside ActorInfo

State

String

No

Actor geo state code as defined in Nayax's backoffice

GeoLocation inside ActorInfo

City

String(255)

No

City as defined in Nayax's backoffice

GeoLocation inside ActorInfo

CountryCode

String

No

Country code (ISO3) as defined in Nayax's backoffice

GeoLocation inside ActorInfo

ZipCode

String(255)

No

Zip code as defined in Nayax's backoffice

GeoLocation inside ActorInfo

Address

String(255)

No

Address as defined in Nayax's backoffice

GeoLocation inside ActorInfo

Longitude

String

No

Machine Location Longitude as defined in Nayax's backoffice

GeoLocation inside ActorInfo

Latitude

String

No

Machine Location Latitude as defined in Nayax's backoffice

CustomData

DirectActor

String

No

Direct actor custom data (String in json format)

Operator

String

No

Operator custom data (String in json format)

Distributor

String

No

Distributor custom data (String in json format)

Actor

String

No

Actor custom data (String in json format)

Machine

String

No

Machine custom data (String in json format)

CardData

CardNumber

String

Yes

For card present Authorization and Sale, the full Track2 will be sent in this field.

For card not present, Settlement, Cancel, Void, Refund - The card PAN only will be sent.

EntryMode

String(4)

Yes

MCR - Card number read from the card magnetic stripe.

CON - Card details read from the chip via the contact interface (insert).

CLS - Card details read from the chip via the contactless interface (tap).

NFC - Card details read from the phone via the contactless interface (phone tap).

CLM - Card track2 read from the chip via the contactless interface (contactless magstripe\legacy mode).

MIF\MIFH - MIFARE\MIFARE received as Hexadecimal.

QR - Card number read from a QR by the DOT


Other values may also be sent in specific edge case, for more information please consult your Nayax POC.

ExpYear

String

No

Conditional- only when Interface is 1 or 10, (YY)

ExpMonth

String

No

Conditional- only when Interface is 1 or 10, (YY)

EMVData

String

No

String of emv tags in TLV format

IDNumber

String

No

IDNumber

RandomNumber

String

No

Further information is unavailable.

BrandInfo inside CardData

PrimaryId

String

No

Primary Brand Id

PrimaryDescription

String

No

Primary Brand Description

SecondaryId

String

No

Secondary Brand Id

CardData

CardHolderName

String

No

Card Holder Name

Products

Code

Int(16)

Yes

Code of the selected item as defined in Nayax's backoffice or vending machine

CatalogProductId

String(100)

No

External unique identifier of the selected item (the product catalog number) as defined in Nayax's backoffice

Name

String(255)

No

Product name as defined in the Nayax backoffice

Price

Double

Yes

Product price in the machine's currency. This the original Product price while the transaction amount is the billing price after adjustments such as surcharge or loyalty.

UnitOfMeasurement

String(64)

No

Product's unit of measurement (e.g 'unit' or 'Liter')

Measurement

Double

No

Product's quantity in the unit of measurement

Group

String(255)

No

Product's group as existing in the product map

ProductGroupId

String(255)

No

Product's group code as existing in the product map

PulseLineNumber

Int(32)

No

Extending remote vend capability to support multiple machines via pulse. positive (PulseLineNumber >= 0)

PaymentInfo

SrvTranId

String

No

The Integrator's internal transaction id.

Conditional, only if /StartSession was not Used.

If /StartSession was used, this should be either empty or Echo the Transaction ID sent in the request.

AuthCode

String(40)

No

External (usually Card issuer's) Authorization Code

AuthAmount

Double

No

Conditional on /Authorization response, optional otherwise.

The original amount requested in /Authorization requested.

SettAmount

Double

No

The original amount requested in /Settlement or /Sale process.
Irrelevant for the Authorization command.

RRN

String

No

Reference Retrieval Number, Used as External Transaction Identification for external parties (Usually Card schemes)
From support perspective - It is highly recommended that this ID shall be the one visible to the end consumer/Card holder.

Token

String(256)

No

A unique token for the transaction. For Internal Nayax use only

AuthDateTime

String

Yes

The date time string of when the /Authorization took place Format: ddMMyyHHmmss

SettDateTime

Double

No

Irrelevant for the Authorization command.

TraceNumber

String

No

Trace number. For Internal Nayax use only

AuthSource

String(5)

No

For Internal Nayax use only

AdditionalData

String

No

String in JSON format.
Contact Nayax TPOC on order define.

IsGatewayTimeout

Bool

No

Was there was a gateway timeout (valid in response)

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

Catergory

Field

Type

Required

Description

Status

Verdict

Sting

Yes

Const string values:
Status of the request ('Approved'/'Declined')

Code

Int(32)

No

Conditional - Only if verdict value is declined

Valid decline codes (must be a code from this list):

1 - Insufficient funds

2 - Transaction ID unknown

3 - Cardholder exceeded daily / weekly / monthly transaction count limit

4 - Cardholder exceeded transaction amount limit

5 - Suspected Fraud

6 - General system failure

7 - Invalid amount

8 - Request cannot be parsed (format error)

9 - Transaction not allowed to cardholder

40 - For Nayax internal use only.

990 - CertificateFileName not found

991 - Failed to decipher message body

992 - Timeout exception

994 - Card Brand not supported

996 - Transaction ID Unknown / Duplicate Transaction ID (Start Session Error)

997 - Missing mandatory parameters

998 - Validation / request cannot be parsed

999 - General exception

1010 - Public Key Certificate not found

1011 - Method not Implemented

StatusMessage

Sting(255)

No

Transaction status message free text field / additional varying data

CustomDeclineCode

String

No

This field is used for specifying a custom decline code (i.e. Soft Decline or Switch Interface). The value might be the same as the acquirer's response code or composed by other data.

Balance

RegularCreditType

Int(32)

No

Enum: 0 1

0 - transactions

1 - amount

RegularCredit

Double

No

Regular Credit amount or amounts of transactions based on RegularCreditType Decimal place 2

RevalueCredit

Int(32)

No

Revalue credit amount - Only if card is configured a revalue-able Decimal place 2

Updated about 5 hours ago