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

Cortina uses the `Start Session` command to notify the integrator about the initialization of the transaction request with the Cortina payment provider.

<Note>
  **Important:** For **Cortina Static QR (SQR)**, the `Start` command is being used instead of StartSession, and `Start` is sent from the Cortina payment provider to Nayax, not the other way around (as mentioned here).
</Note>

More on that in [Static QR- Start](/docs/cortina/staticqr/static-qr-start#/).

## Request

Nayax's servers send a POST request to your configured `StartSession` endpoint, which would be of the following format:

`(customer's URL)/Cortina/StartSession`

The payload includes the following details:

```json theme={null}
{
  "TokenId": "123456",
  "RandomNumber": "123456789qwertyuioasdfghjkl",
  "DynamicURL": "string",
  "CustomData": {
    "DirectActor": "String",
    "Operator": "String",
    "Distributor": "String",
    "Actor": "String",
    "Machine": "String",
    "SoftDecline": "String"
  }
}
```

### Request Parameters

The following table describes all the parameters of the request:

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

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>`TokenId`</td>
      <td style={{ textAlign: "left" }}>String</td>
      <td style={{ textAlign: "left" }}>**Yes**</td>

      <td style={{ textAlign: "left" }}>
        The **3rd party Secret Token** reference number.
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        A unique **27-character random number** generated by Nayax.
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        The **Actor-level URL configuration**. Supports routing to different URLs.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }} colspan="4">
        <strong>Custom Data Fields (String in JSON format)</strong>
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        Custom data for the **Direct Actor** in **JSON format**. Contact Nayax TPOC for definition.
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        Custom data for the **Operator** in **JSON format**. Contact Nayax TPOC for definition.
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        Custom data for the **Distributor** in **JSON format**. Contact Nayax TPOC for definition.
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        Custom data for the **Actor** in **JSON format**. Contact Nayax TPOC for definition.
      </td>
    </tr>

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

      <td style={{ textAlign: "left" }}>
        Custom data for the **Machine** in **JSON format**. Contact Nayax TPOC for definition.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>`SoftDecline` Inside `CustomData`</td>
      <td style={{ textAlign: "left" }}>String</td>
      <td style={{ textAlign: "left" }}>No</td>

      <td style={{ textAlign: "left" }}>
        Custom data related to a **Soft Decline** in **JSON format**. Contact Nayax TPOC for definition.
      </td>
    </tr>
  </tbody>
</table>

## Response

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

```json theme={null}
{
  "TranIDCipher": "a0Qnxm4fWMskzFXiMivn8BDiQVSL6be/NXIICC9HBoAiry6DUdKYPQh/YS1G8nObE6/0o9N4MFuYA7CTAxAnphuNJwBEjgBzKhhgpJ5ggnw=",
  "Status": {
    "Verdict": "Approved",
    "Code": 0,
    "StatusMessage": "string",
    "CustomDeclineCode": "string"
  }
}
```

### Response Parameters

The following table describes all the parameters of the response:

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

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

      <td style={{ textAlign: "left" }}>
        The **encrypted transaction ID** used for authentication in the `/StartSession` request.

        <ul>
          <li>**Integrator's Role:** Generate transaction ID (36 chars/288 bits), append `=` and `RandomNumber` to form the cipher text (64 chars). Encrypt this string using **AES ECB**.</li>
          <li>**AES Key:** The rightmost 256 bits (32 chars) of the Secret Token that matches the `TokenID`.</li>
          <li>**Nayax's Role:** Decrypt the cipher text to extract the transaction ID, which is then used for all subsequent requests.</li>
        </ul>
      </td>
    </tr>

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

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