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

# Start

## Request

The Cortina payment method would send a `Start` command to Nayax's servers in order to notify them about starting a transaction. The call would be of the following format:

`https://lynx.nayax.com/payment/v2/transactions/cortina/(payment method's name)/start`

The payload includes the following details:

<CodeGroup>
  ```json JSON-TerminalID theme={null}
  {
    "AppUserID": "19",
  	"TerminalId": "0456789456789456",
    "TransactionId": "123456789qwertyuioasdfghjkl",
    "SecretToken": "mrV3U3nsgGFrE3w5-wnBo_WCLPce-pZ1awRvTVTkungMIKThTVbj_fiXdfoGclhn0"
  }
  ```

  ```json JSON-UniQR theme={null}
  {
    "AppUserID": "19",
  	"UniQR": "https://qr.nayax.com/v1/rWg_p6pZh1pwjvbkGrmBLy3KgwSz3dq-y63r5FPxk2NOWw2",
    "TransactionId": "123456789qwertyuioasdfghjkl",
    "SecretToken": "mrV3U3nsgGFrE3w5-wnBo_WCLPce-pZ1awRvTVTkungMIKThTVbj_fiXdfoGclhn0"
  }
  ```

  ```json Product selection (relevant only for PreSelection flow) theme={null}
  {
    "AppUserID": "19",
  	"UniQR": "https://qr.nayax.com/v1/rWg_p6pZh1pwjvbkGrmBLy3KgwSz3dq-y63r5FPxk2NOWw2",
    "TransactionId": "123456789qwertyuioasdfghjkl",
    "SecretToken": "mrV3U3nsgGFrE3w5-wnBo_WCLPce-pZ1awRvTVTkungMIKThTVbj_fiXdfoGclhn0"
    "Products":
  	[
  	 {
         "Code":2
   		}
  	]
  }
  ```
</CodeGroup>

### 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>User & Security Identifiers</strong></td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        The consumer's **user ID on the 3rd party's app**.
      </td>
    </tr>

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

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

        <ul>
          <li>Will be echoed in all further requests and responses.</li>
          <li>Minimum length of **8 characters**.</li>
        </ul>
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        The **unique secret key** for your system, provided by Nayax in advance. **Must be kept secret.**
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        The **balance of the user's account**. Decimal value (max 3 digits for cents).
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>Machine Identification (One is Required)</strong></td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        The **Unique Identifier for the vending machine** (HW-Serial of the device).

        <ul>
          <li>**Conditional**: Must be sent if `UniQR` is **not** sent.</li>
        </ul>
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        The **QR code value** linked to the machine.

        <ul>
          <li>**Conditional**: Must be sent if `TerminalId` is **not** sent.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }} colspan="3"><strong>Product Selection (`Products` Array)</strong></td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`Products` Array</td>
      <td style={{ textAlign: "left" }}>\*\*\*</td>

      <td style={{ textAlign: "left" }}>
        The array is **optional**, but if provided, some inner fields are mandatory. Only relevant for the **PreSelection flow**.
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        The **Code of the selected item**.

        <ul>
          <li>**Conditional**: Mandatory if the machine is **not** a Pulse machine.</li>
        </ul>
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        The pulse line number for remote vend capability.

        <ul>
          <li>**Conditional**: Mandatory if the machine is a **Pulse machine**.</li>
          <li>Must be a **positive integer** ($\ge 0$).</li>
        </ul>
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        The **Product name** as defined in the Nayax back office.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`Price` inside `Products`</td>
      <td style={{ textAlign: "left" }}>Double</td>

      <td style={{ textAlign: "left" }}>
        The **original Product price** in the machine's currency.

        <ul>
          <li>**Conditional**: Mandatory if the machine does **not** have a price setup for the product code.</li>
          <li>Note: The transaction amount is the final billing price after adjustments.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`UnitOfMeasurement` inside `Products`</td>
      <td style={{ textAlign: "left" }}>String(64)</td>

      <td style={{ textAlign: "left" }}>
        Product's **unit of measurement** (e.g., 'unit' or 'Liter').
      </td>
    </tr>
  </tbody>
</table>

### Remote Vend: Product Selection

The following applies to the **PreSelection flow** only. To specify which product to vend, include a `"code"` field inside the `"Products"` array with the corresponding product index.

**Pulse machine code numbering**

<u>For Pulse array machines</u> (any Pulse configuration except Pulse Line), the `"code"` numbering starts from 0.\
For example, in case of:

<Frame>
  <img src="https://mintcdn.com/nayax-44d6e37b/1QIVivDOW8wpzFhJ/images/image.png?fit=max&auto=format&n=1QIVivDOW8wpzFhJ&q=85&s=7ec91ecf64188b246d4f9b0648e1967b" alt="Image" width="313" height="553" data-path="images/image.png" />
</Frame>

* `"Code": 0` → **"Ultimate"** product
* `"Code": 1` → **"Superior"** product
* `"Code": 2` → **"Regular"** product

If you send a number outside the scope of the virtual machine's array, our servers will select the first item in the list (`Code: 0`).

<u>For Pulse 1–6 configurations</u> (Pulse Line), use `"PulseLineNumber"` instead of `"code"`, and the counting starts from 1 (not 0).

<Frame>
  <img src="https://mintcdn.com/nayax-44d6e37b/2xlghWOHUXoMSYH1/images/image-2.png?fit=max&auto=format&n=2xlghWOHUXoMSYH1&q=85&s=10cc6ca3a2e7ab60b762a6481c301e8b" alt="Image" width="443" height="324" data-path="images/image-2.png" />
</Frame>

## Response

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

```json theme={null}
{
  "Status": {
    "Verdict": "Approved",
    "StatusMessage": "Cortina V2 Stub Tester"
  }
}
```

### 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` inside `Status`</td>
      <td style={{ textAlign: "left" }}>String</td>

      <td style={{ textAlign: "left" }}>
        The constant string representing the **final status of the request**:

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

    <tr>
      <td style={{ textAlign: "left" }}>`Code` inside `Status`</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 (e.g., 40, 990, 1011).*</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`StatusMessage` inside `Status`</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` inside `Status`</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>
  </tbody>
</table>