Start Session

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

📘
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 in here).

Request

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

(customer's URL)/Cortina/StartSession

The payload includes the following details:

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

Field	Type	Required	Description
`TokenId`	String	Yes	The 3rd party Secret Token reference number.
`RandomNumber`	String	Yes	A unique 27-character random number generated by Nayax.
`DynamicURL`	String(255)	No	The Actor-level URL configuration. Supports routing to different URLs.
Custom Data Fields (String in JSON format)
`DirectActor` Inside `CustomData`	String	No	Custom data for the Direct Actor in JSON format. Contact Nayax TPOC for definition.
`Operator` Inside `CustomData`	String	No	Custom data for the Operator in JSON format. Contact Nayax TPOC for definition.
`Distributor` Inside `CustomData`	String	No	Custom data for the Distributor in JSON format. Contact Nayax TPOC for definition.
`Actor` Inside `CustomData`	String	No	Custom data for the Actor in JSON format. Contact Nayax TPOC for definition.
`Machine` Inside `CustomData`	String	No	Custom data for the Machine in JSON format. Contact Nayax TPOC for definition.
`SoftDecline` Inside `CustomData`	String	No	Custom data related to a Soft Decline in JSON format. Contact Nayax TPOC for definition.

Response

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

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

Request Parameters

The following table describes all the parameters of the request:

Field	Type	Required	Description
`TranIDCipher`	String(36)	Yes	The encrypted transaction ID used for authentication in the `/StartSession` request. 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. AES Key: The rightmost 256 bits (32 chars) of the Secret Token that matches the `TokenID`. Nayax's Role: Decrypt the cipher text to extract the transaction ID, which is then used for all subsequent requests.
`Verdict` inside `Status`	String	Yes	Constant string representing the final status of the request: `Approved` `Declined`
`Code` inside `Status`	Int(32)	No	The Decline Code. Conditional—only present if `Verdict` is 'Declined'. Valid decline 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 documentation for the complete list of error codes.
`StatusMessage` inside `Status`	String(255)	No	A free text field containing the transaction status message or additional varying data regarding the outcome.
`CustomDeclineCode` inside `Status`	String	No	Used for specifying a custom decline code (e.g., related to Soft Decline or Switch Interface). May reflect the acquirer's response code.

Updated 13 days ago