Cancel

Cortina Prepaid uses the Cancelcommand to notify the integrator in order to initiate the cancelation process with the Cortina payment provider whenever on the bellow scenarios takes place:

Getting a failed Authorization Response (either due to timeout or having an error code in the Authorization Response).
Issues during product selection- inactivity of the consumer/Cancel button being pressed/invalid product selection by the consumer.
Vend failure (issue with product dispensing/service providing) by the machine

This command is essential for having the payment provider aware that the transaction was cancelled on Nayax's end (as well as from the consumer's POV), and is done in order for the payment provider to complete the cancellation on it's end.

📘
Note: This command is relevant for PreAuthorization only. It's equivalent of PreSelection flow is the Void command.

Request

Nayax's servers send a POST request to your configured Cancel endpoint, which would be of the following format:

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

The payload includes the full result of the card scan operation:

{
  "ReasonCode": 999,
  "ReasonText": "General exception",
  "BasicInfo": {
    "TransactionId": 2.3658433596983443e+35,
    "NayaxTransactionId": 0,
    "Amount": 0.1,
    "CurrencyCode": "USD",
    "CurrencyNumeric": 376,
    "SiteId": 12,
    "MachineAuTime": "071221132914",
    "TimeoutMS": 15000,
    "IsProductSelected": true
  },
  "DeviceInfo": {
    "HwSerial": "0434324119376526",
    "FWVersion": "4.0.0.22-RC01 - Aug 25 2021",
    "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",
      "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
  }
}

Request Parameters

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

Reference Fields

Field	Type	Description
`ReasonCode`	`Int(16)`	The valid cancellation or decline code: 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 / 998: Request cannot be parsed (format error) / Validation 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 999: General exception 1010: Public Key Certificate not found 1011: Method not Implemented
`ReasonText`	`String`	The verbal explanation corresponding to the `ReasonCode`.
`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.
`Amount`	`Double`	The payment amount (Decimal with max 3 digits for cents). Example: 1 cent = `0.01`. Note: Currencies with no decimal places (e.g., JYN) are still represented as a double (e.g., `234.0`).
`CurrencyCode`	`String(3)`	The currency code in ISO 4217 Alpha-3 format.
`CurrencyNumeric`	`String(3)`	The currency code in ISO 4217 Numeric-3 format.
`SiteId`	`Int(16)`	The identifier for the Nayax server region.
`MachineAuTime`	`String`	The Machine Authorization Timestamp.
`TimeoutMS`	`Int(32)`	Nayax Server Timeout configuration in milliseconds.
`IsProductSelected`	`Bool`	Indication if the product was pre-selected before the payment process.
`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. Contact Nayax TPOC to define.
`DecimalPlace`	`Int(64)`	The decimal point location for amounts used on this machine. Example: Value of `2` means amounts like 123.45.
`Offset`	`String(255)`	UTC timezone offset.
`GroupId`	`String`	For Nayax internal use only.
`OperatorId`	`String(255)`	Merchant ID as defined in Nayax's back office (String format).
`Region`	`String(255)`	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.
`Name`	`String`	Country Full Name.
`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.
`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.
`Longitude`	`String`	Machine Location Longitude.
`Latitude`	`String`	Machine Location Latitude.
`Id`	`Int(64)`	Actor ID (Direct Merchant/Operator).
`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.
`Name`	`String`	Country Full Name.
`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.
`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.
`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).
`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: Magnetic Stripe Read (swipe) CON: Contact Chip Read (insert) CLS: Contactless Chip Read (tap) NFC: Phone/Mobile device contactless read (phone tap) QR: Card number read from a QR code Consult Nayax POC for specific edge cases.
`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 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.
`SrvTranId`	`String`	The Integrator's internal transaction ID. Conditional: Only mandatory if `/StartSession` was not used. If used, this should be empty or echo the Transaction ID.
`AuthCode`	`String(40)`	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 string in JSON format. Contact Nayax TPOC to define.
`IsGatewayTimeout`	`Bool`	Indicates if a gateway timeout occurred (valid in the response).

Response

The Cancel 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
`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 2: Transaction ID unknown 3: Cardholder exceeded 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)	A free text field containing the transaction status message or additional varying data regarding the outcome.
`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.