Refund

Cortina Prepaid uses the Refund command to notify the integrator about a refund request, so the integrator can start the refund with the Cortina payment provider.

How a refund is triggered

You can trigger the refund request in two ways:

From the Dynamic Transaction Monitor in Nayax Core.
Through the Lynx API.

From the Dynamic Transaction Monitor

Refunds Admin role requiredRequesting and approving a refund from the Dynamic Transaction Monitor requires the Refunds Admin role. Ask your Integration Support Engineer to assign it.

Request the refund

Right-click the relevant transaction and select Request Refund.

Nayax Core transaction context menu with Request Refund highlighted

Approve the refund

Right-click the same transaction again and select Approve/Decline Refund.

Nayax Core transaction context menu with Approve/Decline Refund highlighted

Nayax then sends the Refund command to your endpoint, as described below.

Through the Lynx API

Call the Request a Payment Refund endpoint, then the Approve Payment Refund endpoint.

Request

Nayax’s servers send a POST request to your configured Refund endpoint, which would be of the following format: (customer's URL)/Cortina/PrePaid/Refund 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
Transaction Status & Cancellation Codes
`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. 992: Timeout exception 997: Missing mandatory parameters 999: General exception See full list for other status and technical errors (e.g., 990, 994, 1010).
`ReasonText`	String	The verbal explanation corresponding to the `ReasonCode`.
Core Identifiers & Financial Details
`TransactionId`	String(36)	The unique identifier for this transaction. Echoes the encrypted ID from `/StartSession` if used. Otherwise, the Nayax Engine generates this 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: Required if `/StartSession` was not used. If used, it should be empty or echo the Transaction ID.
`Amount`	Double	The payment amount (Decimal with max 3 digits for cents). Example: 1 cent = `0.01`. Note: Currencies with no decimal places are still represented as a double (e.g., 234 JYN = `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.
`AuthCode`	String(40)	External Authorization Code (usually from the Card Issuer’s bank).
`RRN`	String	Reference Retrieval Number (RRN). Highly recommended to be visible to the consumer/card holder for support.
`Token`	String(256)	A unique transaction token. For Nayax internal use only.
`TraceNumber`	String	Trace number. For Nayax internal use only.
`AuthSource`	String(5)	For Nayax internal use only.
Timestamp & System Details
`AuthDateTime`	String	The date and time the `/Authorization` took place. Format:`ddMMyyHHmmss`.
`SettDateTime`	Double	The Settlement Date/Time. Irrelevant for the Authorization command.
`MachineAuTime`	String	Machine Authorization Timestamp.
`TimeoutMS`	Int(32)	Nayax Server Timeout configuration in milliseconds.
`IsGatewayTimeout`	Bool	Indicates if a gateway timeout occurred (valid in the response).
`AdditionalData`	String	Additional data string in JSON format. Contact Nayax TPOC to define.
`SiteId`	Int(16)	Region of the Nayax server.
`IsProductSelected`	Bool	Indication if the product was pre-selected.
Machine & Location Details
`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.
`TerminalId`	String(255)	Terminal identifier. Contact Nayax TPOC to define.
`DecimalPlace`	Int(64)	Decimal point location for amounts.
`Offset`	String(255)	UTC timezone offset.
`GroupId`	String	For Nayax internal use only.
`OperatorId`	String(255)	Merchant ID.
`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.
`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.
`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.
`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).

Response

The Refund 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 & Error Codes
`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 7: Invalid amount 8 / 998: Format/parsing error or Validation error 992: Timeout exception 997: Missing mandatory parameters 999: General exception See full documentation for the complete list of error codes.
`StatusMessage`	String(255)	A free text field containing the transaction status message or additional varying data regarding the outcome.
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.

Cortina Guides

API Reference

How a refund is triggered

From the Dynamic Transaction Monitor

Through the Lynx API

Request

Request parameters

Response

Response parameters

​How a refund is triggered

​From the Dynamic Transaction Monitor

​Through the Lynx API

​Request

​Request parameters

​Response

​Response parameters

How a refund is triggered

From the Dynamic Transaction Monitor

Through the Lynx API

Request

Request parameters

Response

Response parameters