Refund

Cortina DQR 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/DynamicQR/Refund The payload includes the full result of the card scan operation:

{
  "ReasonCode": 0,
  "ReasonText": "string",
  "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"
  },
  "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:

Field	Type	Description
Transaction Identifiers & References
`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.
`RRN`	String	Reference Retrieval Number (RRN). Recommended to be visible to the consumer/card holder for support.
`AuthCode`	String(40)	External Authorization Code (usually from the Card Issuer’s bank).
`Token`	String(256)	A unique token for the transaction. For Nayax internal use only.
`TraceNumber`	String	Trace number. For Nayax internal use only.
`AuthSource`	String(5)	For Nayax internal use only.
`InitiateTranReference`	String	Conditional: Reflects the original Nayax Transaction ID for prepaid loyalty card re-attempts. Provided as a String in JSON format.
Financial & Time Details
`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.
`AuthDateTime`	String	The date and time the `/Authorization` took place. Format:`ddMMyyHHmmss`.
`SettDateTime`	Double	The Settlement Date/Time. Irrelevant for the Authorization command.
`CurrencyCode`	String(3)	Currency code in ISO 4217 Alpha-3 format.
`CurrencyNumeric`	String(3)	Currency code in ISO 4217 Numeric-3 format.
Card & Payment Details
`CardNumber`	String	Card details provided based on transaction type: Full Track 2 for card-present Authorization/Sale. Card PAN only for other transaction types.
`EntryMode`	String(4)	How the card details were read: MCR: Magnetic Stripe Read (swipe) CON: Contact Chip (insert) CLS: Contactless Chip (tap) NFC: Phone/Mobile contactless QR: QR code read by DOT 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.
`IsRevalueCard`	Bool	Indication if card is allowed revalue.
System & External Data
`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.
`ProviderExternalData`	String	External data from the provider in JSON format string.

Response

The Refund Response that the customer’s payment method would send to Nayax’s servers.
The payload should look as follows:

{
  "Status": {
    "Verdict": "string",
    "Code": 0,
    "StatusMessage": "string",
    "CustomDeclineCode": "string"
  },
  "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
  }
}

Response parameters

The following table describes the fields returned in the API response:

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 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 list for other status and internal errors.
`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 (e.g., related to Soft Decline or Switch Interface). May reflect the acquirer’s response code.
Financial & Time Details
`AuthAmount`	Double	The original amount requested in the `/GenerateQR` request.
`SettAmount`	Double	The original amount requested in `/Settlement` or `/Sale` process. Conditional on `/Inquiry` request.
`AuthDateTime`	String	The date and time the `/Authorization` or `/Sale` took place. Format:`ddMMyyHHmmss`.
`SettDateTime`	String	The date and time the `/Settlement` or `/Sale` took place. Format:`ddMMyyHHmmss`.
Transaction Identifiers & References
`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.
`AuthCode`	String(40)	External Authorization Code (usually from the Card Issuer’s bank).
`RRN`	String	Reference Retrieval Number (RRN). Used as External Transaction ID for external parties (e.g., Card schemes). Highly recommended to be visible to the consumer/card holder for support. Note: The RRN must match the preceding value sent in the `/GenerateQR` response for an `/Inquiry` request.
`Token`	String(256)	A unique token for the transaction. For Nayax internal use only.
`TraceNumber`	String	Trace number. For Nayax internal use only.
`AuthSource`	String(5)	For Nayax internal use only.
`InitiateTranReference`	Int(64)	Conditional: Reflects the original Nayax Transaction ID for prepaid loyalty card re-attempts.
Loyalty & System Details
`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.
`IsRevalueCard`	Bool	Indication if card is allowed revalue.
`IsGatewayTimeout`	Bool	Indicates if a gateway timeout occurred (valid in the response).
`ProviderExternalData`	String	External data from the provider in JSON format string.
`AdditionalData`	String	Additional data string in JSON format.

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