Skip to main content
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).
More on that in Static QR- Start.

​
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:
FieldTypeRequiredDescription
TokenIdStringYesThe 3rd party Secret Token reference number.
RandomNumberStringYesA unique 27-character random number generated by Nayax.
DynamicURLString(255)NoThe Actor-level URL configuration. Supports routing to different URLs.
DirectActor Inside CustomDataStringNoCustom data for the Direct Actor in JSON format. Contact Nayax TPOC for definition.
Operator Inside CustomDataStringNoCustom data for the Operator in JSON format. Contact Nayax TPOC for definition.
Distributor Inside CustomDataStringNoCustom data for the Distributor in JSON format. Contact Nayax TPOC for definition.
Actor Inside CustomDataStringNoCustom data for the Actor in JSON format. Contact Nayax TPOC for definition.
Machine Inside CustomDataStringNoCustom data for the Machine in JSON format. Contact Nayax TPOC for definition.
SoftDecline Inside CustomDataStringNoCustom 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:
FieldTypeRequiredDescription
TranIDCipherString(36)YesThe 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 StatusStringYesConstant string representing the final status of the request:
  • Approved
  • Declined
Code inside StatusInt(32)NoThe 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 StatusString(255)NoA free text field containing the transaction status message or additional varying data regarding the outcome.
CustomDeclineCode inside StatusStringNoUsed for specifying a custom decline code (e.g., related to Soft Decline or Switch Interface). May reflect the acquirer’s response code.