> ## 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 Prepaid uses the `Refund` command to notify the integrator about the refund request in order to initiate the authorization 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/PrePaid/Refund`

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

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

<Accordion title="Reference Fields">
  <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 & Cancellation Codes</strong></td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          The valid **cancellation or decline code**:

          <ul>
            <li>**1:** Insufficient funds</li>
            <li>**2:** Transaction ID unknown</li>
            <li>**3:** Cardholder exceeded daily/weekly/monthly transaction count limit</li>
            <li>**4:** Cardholder exceeded transaction amount limit</li>
            <li>**5:** Suspected Fraud</li>
            <li>**6:** General system failure</li>
            <li>**7:** Invalid amount</li>
            <li>**8 / 998:** Request cannot be parsed (format error) / Validation error</li>
            <li>**9:** Transaction not allowed to cardholder</li>
            <li>**40:** For Nayax internal use only.</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 technical errors (e.g., 990, 994, 1010).*</li>
          </ul>
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          The **verbal explanation** corresponding to the `ReasonCode`.
        </td>
      </tr>

      <tr>
        <td style={{ textAlign: "left" }} colspan="3"><strong>Core Identifiers & Financial Details</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" }}>`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" }}>`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)**. Highly recommended to be visible to the **consumer/card holder** for support.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          A unique transaction token. **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" }} colspan="3"><strong>Timestamp & System Details</strong></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" }}>`MachineAuTime`</td>
        <td style={{ textAlign: "left" }}>String</td>

        <td style={{ textAlign: "left" }}>
          **Machine Authorization Timestamp**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Nayax Server **Timeout configuration** in milliseconds.
        </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" }}>`SiteId`</td>
        <td style={{ textAlign: "left" }}>Int(16)</td>

        <td style={{ textAlign: "left" }}>
          Region of the **Nayax server**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Indication if the product was **pre-selected**.
        </td>
      </tr>

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

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

        <td style={{ textAlign: "left" }}>
          Nayax Device **Hardware serial number**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Device **Firmware version**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Nayax Device Type.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          **Machine entity unique ID**.
        </td>
      </tr>

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

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

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

        <td style={{ textAlign: "left" }}>
          **Terminal identifier**. Contact Nayax TPOC to define.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          **Decimal point location** for amounts.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          **UTC timezone offset**.
        </td>
      </tr>

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

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

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

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

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

        <td style={{ textAlign: "left" }}>
          Machine **Region**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Machine **City**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Machine **Zip Code**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Country **Full Name** (for machine location).
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          **ISO-3166-1 Numeric-3 code**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          **ISO-3166-1 Alpha-2 code**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          **ISO-3166-1 Alpha-3 code**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Actor geo **state code**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Actor geo **City**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Actor geo **Country code (ISO3)**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Actor geo **Zip code**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Actor geo **Address**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Machine Location **Longitude**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Machine Location **Latitude**.
        </td>
      </tr>

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

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

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

        <td style={{ textAlign: "left" }}>
          **Direct Merchant name**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          **Merchant operator ID** (Integer format).
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          **Merchant operator name**.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          **Merchant ID**. Contact Nayax TPOC to define.
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Direct actor **custom data** (String in **JSON format**).
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Operator **custom data** (String in **JSON format**).
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Distributor **custom data** (String in **JSON format**).
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Actor **custom data** (String in **JSON format**).
        </td>
      </tr>

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

        <td style={{ textAlign: "left" }}>
          Machine **custom data** (String in **JSON format**).
        </td>
      </tr>
    </tbody>
  </table>
</Accordion>

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

<Accordion title="Reference Fields">
  <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 decline 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 documentation for the complete list of error codes.*</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" }} colspan="3"><strong>Loyalty & Credit Information</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**.

          <ul>
            <li>**Only present** if the associated card is configured as revalue-able.</li>
            <li>**Uses Decimal place 2.**</li>
          </ul>
        </td>
      </tr>
    </tbody>
  </table>
</Accordion>