Authorization

Cortina Prepaid uses the Authorization command to notify about the result of a card tap 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 Authorization endpoint, which would be of the following format: (customer's URL)/Cortina/PrePaid/Authorization The payload includes the full result of the card scan operation:

{
  "BasicInfo": {
    "TransactionId": "N99O4XURDQYJZIK4OTCAWF1RHHA40TZWVCRB",
    "NayaxTransactionId": 3584697384,
    "Amount": 5,
    "CurrencyCode": "ILS",
    "CurrencyNumeric": "376",
    "SiteId": 1,
    "MachineAuTime": "071221132914",
    "TimeoutMS": 15000,
    "IsProductSelected": true,
    "PaymentMethodID": 1,
    "BillingProviderId": 1,
    "AuditNumber": 342,
    "NayaxRRN": "111111",
    "IsDeferredAuthorization": true,
    "AgeLimitation": 18,
    "IsSoftDeclineCompletion": true,
    "TransitElement": {
      "TransitTransactionType": 1,
      "DenyListIndication": 0
    }
  },
  "DeviceInfo": {
    "HwSerial": "0434324119376526",
    "FWVersion": "4.0.0.22-RC01 - Aug 25 2021",
    "Type": "Onyx"
  },
  "MachineInfo": {
    "Id": 106791869,
    "Name": "Itai_TestPayCC V2",
    "ExternalId": "OperatorExternalID",
    "Type": "machine type",
    "TerminalId": "8888888844",
    "DecimalPlace": 2,
    "Offset": "3.00",
    "GroupId": "String",
    "OperatorId": 2001537302,
    "Region": "EU",
    "City": "Abbeville",
    "ZipCode": "22448Z",
    "Country": {
      "Name": "UNITED STATES",
      "NumericCode": "840",
      "Alpha2Code": "US",
      "Alpha3Code": "USA",
      "Intra": "Europe"
    },
    "GeoLocation": {
      "State": "Alabama",
      "City": "Zambezi",
      "CountryCode": "ZM",
      "ZipCode": "234234",
      "Address": "River",
      "Latitude": 51.0003431,
      "Longitude": 23.745245
    }
  },
  "ActorInfo": {
    "Id": 2001537302,
    "Name": "TestPayCC V2 OP",
    "OperatorId": 2001537302,
    "OperatorName": "TestPayCC V2 OP _ Sub Merchant",
    "MerchantId": 999999888885,
    "DynamicURL": "https://www.nayax.com/alternativeURL",
    "Country": {
      "Name": "UNITED STATES",
      "NumericCode": "840",
      "Alpha2Code": "US",
      "Alpha3Code": "USA",
      "Intra": "Europe"
    },
    "GeoLocation": {
      "State": "Alabama",
      "City": "Zambezi",
      "CountryCode": "ZM",
      "ZipCode": "234234",
      "Address": "River",
      "Latitude": 51.0003431,
      "Longitude": 23.745245
    },
    "MCC": 455,
    "SubMerchantId": 999999888886
  },
  "CustomData": {
    "DirectActor": "String",
    "Operator": "String",
    "Distributor": "String",
    "Actor": "String",
    "Machine": "String",
    "SoftDecline": "String"
  },
  "CardData": {
    "CardNumber": "****",
    "EntryMode": "MCR",
    "ExpYear": "23",
    "ExpMonth": "01",
    "EMVData": "string",
    "CVV2": "****",
    "IDNumber": "****",
    "RandomNumber": "string",
    "BrandInfo": {
      "PrimaryId": "6",
      "PrimaryDescription": "VISA",
      "SecondaryId": "0",
      "SecondaryDescription": "string"
    },
    "CardHolderName": "Test Card Holder",
    "IsDebitCard": true
  },
  "PaymentInfo": {
    "SrvTranId": "3584697388",
    "AuthCode": "333333",
    "AuthAmount": 5.5,
    "SettAmount": 5.5,
    "RRN": "111111",
    "Token": "string",
    "AuthDateTime": "071221133300",
    "SettDateTime": "071221133330",
    "TraceNumber": "4444",
    "AuthSource": "string",
    "AdditionalData": "string",
    "IsGatewayTimeout": false,
    "ProviderExternalData": "string",
    "InitiateTranReference": 11223344,
    "IsRevalueCard": false
  }
}

Request Parameters

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

Reference Fields

Field	Type	Description
`TransactionId`	String(36)	The unique identifier for this transaction. If `/StartSession` was used, this echoes the ID encrypted in ‘TranIDCipher’. If `/StartSession` was not used, the Nayax Engine generates this value.
`NayaxTransactionId`	Int(64)	The Nayax internal unique identifier for the transaction. This ID is echoed in further related requests.
`Amount`	Double	The payment amount (Decimal with max 3 digits for cents). Example: 1 cent = `0.01`, 20 cents = `0.20`. Note: Currencies with no decimal places (e.g., JYN) are still represented as a double, e.g., 234 JYN = `234.0`.
`CurrencyCode`	String(3)	The currency represented by its ISO 4217 Alpha-3 code (e.g., USD, EUR).
`CurrencyNumeric`	String(3)	The currency represented by its ISO 4217 Numeric-3 code (e.g., 840 for USD).
`SiteId`	Int(16)	The identifier for the Nayax server region hosting the transaction.
`MachineAuTime`	String	The Machine Authorization Timestamp.
`TimeoutMS`	Int(32)	The Nayax Server Timeout configuration, specified in milliseconds.
`IsProductSelected`	Bool	Indication of whether the product was pre-selected before the payment process began.
`PaymentMethodID`	Int(32)	The Nayax identifier for the specific payment provider used.
`BillingProviderId`	Int(32)	The Nayax identifier for the associated billing provider.
`AuditNumber`	Int(64)	Field reserved for Nayax internal use only.
`NayaxRRN`	String	A Reference Number used as an External Transaction Identification for external parties. Recommendation: This ID should be visible to the end consumer and their bank/service provider. This value must be repeated in the subsequent `/Inquiry` request.
`IsDeferredAuthorization`	Bool	Boolean indicator. Further information is unavailable.
`AgeLimitation`	Int(16)	The minimum age required to permit the transaction.
`IsSoftDeclineCompletion`	Bool	Boolean indicator. Further information is unavailable.
`TransitTransactionType`	Int(32)	The transaction type for transit payments (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 will cause the consumer to be added to the deny list. 2: Approval shall cause the consumer to be removed from the deny list.
`HwSerial`	String	The Nayax Device Hardware serial number.
`FWVersion`	String	The device Firmware version number.
`Type`	String	The Nayax Device Type.
`Id`	Int(64)	The unique machine entity ID allocated in Nayax’s back office system.
`Name`	String(255)	The Machine Name as configured in Nayax’s back office.
`ExternalId`	String(200)	The Machine External ID (Machine number - operator) provided by the operator in Nayax’s back office.
`Type`	String(50)	The Machine Type as defined in Nayax’s back office.
`TerminalId`	String(255)	The Terminal identifier. Contact Nayax TPOC for definition.
`DecimalPlace`	Int(64)	The decimal point location for amounts used on this machine. Example: Value of `2` means amounts like 123.45. Example: Value of `0` means amounts like 12345 (integer representation).
`Offset`	String(255)	The UTC timezone offset for the machine’s location.
`GroupId`	String	Field reserved for Nayax internal use only.
`OperatorId`	String(255)	The Merchant ID as defined in Nayax’s back office.
`Region`	String(255)	The Region as defined in Nayax’s back office.
`City`	String(255)	The machine’s City as defined in Nayax’s back office.
`ZipCode`	String(255)	The machine’s Zip Code as defined in Nayax’s back office.
`Name`	String	The Country Full Name.
`NumericCode`	String(3)	The ISO-3166-1 Numeric-3 code for the country (e.g., 840).
`Alpha2Code`	String(2)	The ISO-3166-1 Alpha-2 code for the country (e.g., US).
`Alpha3Code`	String(3)	The ISO-3166-1 Alpha-3 code for the country (e.g., USA).
`Intra`	String	The Intra Region for geographical diversification.
`State`	String	The Actor geo state code.
`City`	String(255)	The City associated with the actor.
`CountryCode`	String	The Country code (ISO3).
`ZipCode`	String(255)	The Zip Code associated with the actor.
`Address`	String(255)	The Address associated with the actor.
`Latitude`	String	The Machine Location Latitude.
`Longitude`	String	The Machine Location Longitude.
`Id`	Int(64)	The Actor ID.
`Name`	String(255)	The Direct Merchant Name.
`OperatorId`	Int(64)	The Merchant Operator ID.
`OperatorName`	String	The Merchant Operator Name.
`MerchantId`	Int(64)	The Merchant ID. Contact Nayax TPOC to define.
`DynamicURL`	String	The Actor level URL configuration.
`Name`	String	The Country Full Name.
`NumericCode`	String(3)	The ISO-3166-1 Numeric-3 code.
`Alpha2Code`	String(2)	The ISO-3166-1 Alpha-2 code.
`Alpha3Code`	String(3)	The ISO-3166-1 Alpha-3 code.
`Intra`	String	The Intra Region for geographical diversification.
`State`	String	The Actor geo state code.
`City`	String(255)	The City associated with the actor.
`CountryCode`	String	The Country code (ISO3).
`ZipCode`	String(255)	The Zip Code associated with the actor.
`Address`	String(255)	The Address associated with the actor.
`Latitude`	String	The Machine Location Latitude.
`Longitude`	String	The Machine Location Longitude.
`MCC`	Int(32)	Merchant Category Code. Used to classify merchants by the type of goods or services provided.
`SubMerchantId`	String(255)	The Sub Merchant identifier. Contact Nayax TPOC to define.
`DirectActor`	String	Custom data for the Direct Actor in JSON format.
`Operator`	String	Custom data for the Operator in JSON format.
`Distributor`	String	Custom data for the Distributor in JSON format.
`Actor`	String	Custom data for the Actor in JSON format.
`Machine`	String	Custom data for the Machine in JSON format.
`SoftDecline`	String	Custom data related to a Soft Decline in JSON format.
`CardNumber`	String	Card details sent based on transaction type: For Card Present Authorization/Sale: The full Track2 data. For other transactions: The card PAN only.
`EntryMode`	String(4)	Indicates how the card details were read. Common values include: MCR: Magnetic Stripe Read (swipe). CON: Contact Chip Read (insert). CLS: Contactless Chip Read (tap). NFC: Phone/Mobile device contactless read. QR: Card number read from a QR code.
`ExpYear`	String	The card’s expiration year (YY format). Conditional: Only sent when Interface is 1 or 10.
`ExpMonth`	String	The card’s expiration month (MM format). Conditional: Only sent when Interface is 1 or 10.
`EMVData`	String	A string containing EMV tags in TLV (Tag-Length-Value) format.
`CVV2`	String	The Card Verification Value 2 (CVV2).
`IDNumber`	String	The ID Number associated with the cardholder or transaction.
`RandomNumber`	String	Further information is unavailable.
`PrimaryId`	String	The Primary Brand Id.
`PrimaryDescription`	String	The Primary Brand Description.
`SecondaryId`	String	The Secondary Brand Id (if applicable).
`SecondaryDescription`	String	The Secondary Brand Description (if applicable).
`CardHolderName`	String	The Card Holder Name.
`IsDebitCard`	Bool	Indication if card is a Debit or Prepaid card.
`SrvTranId`	String	The Integrator’s internal transaction ID. Conditional: Only mandatory if `/StartSession` was not used. If `/StartSession` was used, this should be empty or echo the main Transaction ID.
`AuthCode`	String(40)	The External Authorization Code (usually from the Card Issuer’s bank).
`AuthAmount`	Double	The original amount requested in the `/Authorization` request.
`SettAmount`	Double	The original amount requested in the `/Settlement` or `/Sale` process. Irrelevant for Authorization.
`RRN`	String	Reference Retrieval Number. Highly recommended to be visible to the end consumer/card holder.
`Token`	String(256)	A unique token for the transaction. For Nayax Internal use only.
`AuthDateTime`	String	The date and time string when the `/Authorization` took place. Format:`ddMMyyHHmmss`.
`SettDateTime`	Double	The Settlement Date/Time. Irrelevant for Authorization.
`TraceNumber`	String	The Trace Number. For Nayax Internal use only.
`AuthSource`	String(5)	For Nayax Internal use only.
`AdditionalData`	String	Additional data sent as a JSON format string.
`IsGatewayTimeout`	Bool	Indication of whether a gateway timeout occurred.
`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 of whether the card is allowed to be revalued.

Response

The Authorization 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 constant string status of the request: `Approved` `Declined`
`Code`	Int(32)	Conditional: Only returned if `Verdict` is Declined. The mandatory decline codes: 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`	String(255)	The transaction status message, provided as a free text field or for additional varying data.
`CustomDeclineCode`	String	Used to specify a custom decline code (e.g., for Soft Decline or Switch Interface). This value may be the acquirer’s response code or composed of other data.
`SrvTranId`	String	The Integrator’s internal transaction ID. Conditional: Only mandatory if `/StartSession` was not used. If `/StartSession` was used, this should be empty or echo the Transaction ID sent in the request.
`AuthCode`	String(40)	The External Authorization Code (usually from the Card Issuer’s bank).
`AuthAmount`	Double	The original amount requested in the `/Authorization` Request.
`SettAmount`	Double	The original amount requested in the `/Settlement` or `/Sale` process. Irrelevant for Authorization.
`RRN`	String	Reference Retrieval Number. Highly recommended to be visible to the end consumer/card holder for support.
`Token`	String(256)	A unique token for the transaction. For Nayax Internal use only.
`AuthDateTime`	String	The date and time string when the `/Authorization` took place. Format:`ddMMyyHHmmss`.
`SettDateTime`	Double	The Settlement Date/Time. Irrelevant for Authorization.
`TraceNumber`	String	The Trace Number. For Nayax Internal use only.
`AuthSource`	String(5)	For Nayax Internal use only.
`AdditionalData`	String	Additional data sent as a JSON format string. Contact Nayax TPOC to define.
`IsGatewayTimeout`	Bool	Indication (valid in response) of whether a gateway timeout occurred.
`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 of whether the card is allowed to be revalued (have funds added).
`RegularCreditType`	Int(32)	Defines what the `RegularCredit` field represents (Enum values): 0: The credit is counted in transactions. 1: The credit is counted as an amount.
`RegularCredit`	Double	The Regular Credit amount or number of transactions based on `RegularCreditType`. Decimal place 2.
`RevalueCredit`	Int(32)	The Revalue Credit amount. Only available if the card is configured as revalue-able. Decimal place 2.

Cortina Guides

API Reference

Request

Request Parameters

Response

Response Parameters

​Request

​Request Parameters

​Response

​Response Parameters

Request

Request Parameters

Response

Response Parameters