> ## Documentation Index
> Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refund

Cortina DQR uses the `Refund` command to notify the integrator about the refund request in order to initiate the refund process with the Cortina payment provider.\
Said request would be triggered via either of the following options:

* Nayax's Dynamic Transaction Monitor by selecting the relevant transaction, right-clicking on it and then selecting "Request Refund".
* Nayax's Lynx API- via the Refund command

## 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:

```json theme={null}
{
  "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:

<table>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>Field</th>
      <th style={{ textAlign: "left" }}>Type</th>
      <th style={{ textAlign: "left" }}>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>Transaction Identifiers & References</strong></td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`TransactionId`</td>
      <td style={{ textAlign: "left" }}>String(36)</td>

      <td style={{ textAlign: "left" }}>
        The **unique identifier** for this transaction.

        <ul>
          <li>Echoes the encrypted ID from `/StartSession` if used.</li>
          <li>Otherwise, the **Nayax Engine** generates this value.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`NayaxTransactionId`</td>
      <td style={{ textAlign: "left" }}>Int(64)</td>

      <td style={{ textAlign: "left" }}>
        The **Nayax internal unique ID** for the transaction, echoed in further requests.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`SrvTranId`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        The **Integrator's internal transaction ID**.

        <ul>
          <li>**Conditional**: Required if `/StartSession` was **not** used.</li>
          <li>If used, it should be empty or echo the Transaction ID.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`RRN`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        **Reference Retrieval Number (RRN)**. Recommended to be visible to the **consumer/card holder** for support.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AuthCode`</td>
      <td style={{ textAlign: "left" }}>String(40)</td>

      <td style={{ textAlign: "left" }}>
        **External Authorization Code** (usually from the Card Issuer's bank).
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`Token`</td>
      <td style={{ textAlign: "left" }}>String(256)</td>

      <td style={{ textAlign: "left" }}>
        A unique token for the transaction. **For Nayax internal use only.**
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`TraceNumber`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Trace number. **For Nayax internal use only.**
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AuthSource`</td>
      <td style={{ textAlign: "left" }}>String(5)</td>

      <td style={{ textAlign: "left" }}>
        **For Nayax internal use only.**
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`InitiateTranReference`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        **Conditional**: Reflects the original Nayax Transaction ID for prepaid loyalty card re-attempts. Provided as a String in **JSON format**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>Financial & Time Details</strong></td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`Amount`</td>
      <td style={{ textAlign: "left" }}>Double</td>

      <td style={{ textAlign: "left" }}>
        The **payment amount** (Decimal with max 3 digits for cents).

        <ul>
          <li>Example: 1 cent = `0.01`.</li>
          <li>**Note:** Currencies with no decimal places are still represented as a double (e.g., 234 JYN = `234.0`).</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AuthAmount`</td>
      <td style={{ textAlign: "left" }}>Double</td>

      <td style={{ textAlign: "left" }}>
        The **original amount requested** in the `/Authorization` request. Conditional on `/Authorization` response.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`SettAmount`</td>
      <td style={{ textAlign: "left" }}>Double</td>

      <td style={{ textAlign: "left" }}>
        The original amount requested in the `/Settlement` or `/Sale` process. **Irrelevant for the Authorization command**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AuthDateTime`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        The date and time the `/Authorization` took place. **Format:`ddMMyyHHmmss`**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`SettDateTime`</td>
      <td style={{ textAlign: "left" }}>Double</td>

      <td style={{ textAlign: "left" }}>
        The Settlement Date/Time. Irrelevant for the Authorization command.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`CurrencyCode`</td>
      <td style={{ textAlign: "left" }}>String(3)</td>

      <td style={{ textAlign: "left" }}>
        Currency code in **ISO 4217 Alpha-3** format.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`CurrencyNumeric`</td>
      <td style={{ textAlign: "left" }}>String(3)</td>

      <td style={{ textAlign: "left" }}>
        Currency code in **ISO 4217 Numeric-3** format.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>Card & Payment Details</strong></td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`CardNumber`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Card details provided based on transaction type:

        <ul>
          <li>Full **Track 2** for card-present Authorization/Sale.</li>
          <li>Card **PAN only** for other transaction types.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`EntryMode`</td>
      <td style={{ textAlign: "left" }}>String(4)</td>

      <td style={{ textAlign: "left" }}>
        **How the card details were read**:

        <ul>
          <li>**MCR**: Magnetic Stripe Read (swipe)</li>
          <li>**CON**: Contact Chip (insert)</li>
          <li>**CLS**: Contactless Chip (tap)</li>
          <li>**NFC**: Phone/Mobile contactless</li>
          <li>**QR**: QR code read by DOT</li>
          <li>*Consult Nayax POC for specific edge cases.*</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`ExpYear`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Card expiration year (**YY** format). **Conditional** (only when Interface is 1 or 10).
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`ExpMonth`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Card expiration month (**MM** format). **Conditional** (only when Interface is 1 or 10).
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`EMVData`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        EMV tags data in **TLV (Tag-Length-Value) format**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`IDNumber`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Cardholder **ID Number**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`RandomNumber`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Further information is unavailable.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`PrimaryId`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        **Primary Brand ID**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`PrimaryDescription`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        **Primary Brand Description**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`SecondaryId`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        **Secondary Brand ID**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`SecondaryDescription`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        **Secondary Brand Description**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`CardHolderName`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        **Card Holder Name**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`IsRevalueCard`</td>
      <td style={{ textAlign: "left" }}>Bool</td>

      <td style={{ textAlign: "left" }}>
        Indication if card is **allowed revalue**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>System & External Data</strong></td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`IsGatewayTimeout`</td>
      <td style={{ textAlign: "left" }}>Bool</td>

      <td style={{ textAlign: "left" }}>
        Indicates if a **gateway timeout** occurred (valid in the response).
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AdditionalData`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Additional data string in **JSON format**. Contact Nayax TPOC to define.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`ProviderExternalData`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        External data from the provider in **JSON format string**.
      </td>
    </tr>
  </tbody>
</table>

## Response

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

```json theme={null}
{
  "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:

<table>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>Field</th>
      <th style={{ textAlign: "left" }}>Type</th>
      <th style={{ textAlign: "left" }}>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>Transaction Status & Error Codes</strong></td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`Verdict`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        The final status of the request. Must be one of the constant string values:

        <ul>
          <li>**`Approved`**</li>
          <li>**`Declined`**</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`Code`</td>
      <td style={{ textAlign: "left" }}>Int(32)</td>

      <td style={{ textAlign: "left" }}>
        The **Decline Code**. **Conditional**—only present if `Verdict` is 'Declined'. Valid codes include:

        <ul>
          <li>**1:** Insufficient funds</li>
          <li>**5:** Suspected Fraud</li>
          <li>**6:** General system failure</li>
          <li>**7:** Invalid amount</li>
          <li>**8 / 998:** Format/parsing error or Validation error</li>
          <li>**992:** Timeout exception</li>
          <li>**997:** Missing mandatory parameters</li>
          <li>**999:** General exception</li>
          <li>*See full list for other status and internal errors.*</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`StatusMessage`</td>
      <td style={{ textAlign: "left" }}>String(255)</td>

      <td style={{ textAlign: "left" }}>
        A free text field containing the **transaction status message** or additional varying data regarding the outcome.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`CustomDeclineCode`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Used for specifying a **custom decline code** (e.g., related to Soft Decline or Switch Interface). May reflect the acquirer's response code.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>Financial & Time Details</strong></td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AuthAmount`</td>
      <td style={{ textAlign: "left" }}>Double</td>

      <td style={{ textAlign: "left" }}>
        The **original amount requested** in the `/GenerateQR` request.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`SettAmount`</td>
      <td style={{ textAlign: "left" }}>Double</td>

      <td style={{ textAlign: "left" }}>
        The original amount requested in `/Settlement` or `/Sale` process. **Conditional** on `/Inquiry` request.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AuthDateTime`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        The date and time the `/Authorization` or `/Sale` took place. **Format:`ddMMyyHHmmss`**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`SettDateTime`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        The date and time the `/Settlement` or `/Sale` took place. **Format:`ddMMyyHHmmss`**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>Transaction Identifiers & References</strong></td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`SrvTranId`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        The **Integrator's internal transaction ID**.

        <ul>
          <li>**Conditional**: Required if `/StartSession` was **not** used.</li>
          <li>If used, it should be empty or echo the Transaction ID.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AuthCode`</td>
      <td style={{ textAlign: "left" }}>String(40)</td>

      <td style={{ textAlign: "left" }}>
        **External Authorization Code** (usually from the Card Issuer's bank).
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`RRN`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        **Reference Retrieval Number (RRN)**.

        <ul>
          <li>Used as External Transaction ID for external parties (e.g., Card schemes).</li>
          <li>Highly recommended to be visible to the **consumer/card holder** for support.</li>
          <li>**Note:** The RRN must **match** the preceding value sent in the `/GenerateQR` response for an `/Inquiry` request.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`Token`</td>
      <td style={{ textAlign: "left" }}>String(256)</td>

      <td style={{ textAlign: "left" }}>
        A unique token for the transaction. **For Nayax internal use only.**
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`TraceNumber`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Trace number. **For Nayax internal use only.**
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AuthSource`</td>
      <td style={{ textAlign: "left" }}>String(5)</td>

      <td style={{ textAlign: "left" }}>
        **For Nayax internal use only.**
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`InitiateTranReference`</td>
      <td style={{ textAlign: "left" }}>Int(64)</td>

      <td style={{ textAlign: "left" }}>
        **Conditional**: Reflects the **original Nayax Transaction ID** for prepaid loyalty card re-attempts.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>Loyalty & System Details</strong></td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`RegularCreditType`</td>
      <td style={{ textAlign: "left" }}>Int(32)</td>

      <td style={{ textAlign: "left" }}>
        Defines the unit of measure for `RegularCredit` (Enum values):

        <ul>
          <li>**0:** Credit is counted in **transactions** (count).</li>
          <li>**1:** Credit is counted as an **amount** (currency).</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`RegularCredit`</td>
      <td style={{ textAlign: "left" }}>Double</td>

      <td style={{ textAlign: "left" }}>
        The regular credit value (amount or transaction count) based on the `RegularCreditType`. **Uses Decimal place 2.**
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`RevalueCredit`</td>
      <td style={{ textAlign: "left" }}>Int(32)</td>

      <td style={{ textAlign: "left" }}>
        The **revalue credit amount**. **Only present** if the associated card is configured as revalue-able.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`IsRevalueCard`</td>
      <td style={{ textAlign: "left" }}>Bool</td>

      <td style={{ textAlign: "left" }}>
        Indication if card is **allowed revalue**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`IsGatewayTimeout`</td>
      <td style={{ textAlign: "left" }}>Bool</td>

      <td style={{ textAlign: "left" }}>
        Indicates if a **gateway timeout** occurred (valid in the response).
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`ProviderExternalData`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        External data from the provider in **JSON format string**.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`AdditionalData`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        Additional data string in **JSON format**.
      </td>
    </tr>
  </tbody>
</table>