logo
API docs by Redocly

Nayax Cortina API (v2.1)

Download OpenAPI specification:Download

Credit Card, Prepaid, DynamicQR, StaticQR APIs

Cortina

Business Case

Overview

Welcome to Cortina API Payment Solution. The Cortina is collection of API methods allow a payment gateway (an Integrator) to process payment via Nayax systems. Cortina supports the following payment methods -

  • Credit Cards
  • Prepaid Cards
  • Static QR
  • Dynamic QR

We are offering 2 payment flows to address your needs -

  • Pre-authorization - A 2 steps payment approach in which Nayax first authorize hold on default amount in the consumer balance (prior to consumer choosing a product (/service)), following by a finalizing settlement on the actual amount according to the Product (/service) the consumer has received. External Prepaid Flow
  • Preselection - A 1 step sale approach in which the desired product (or a service) by the consumer is already known, and the payment will be on that actual amount. External Prepaid Flow

Age Verification

The Age Verification flow provides a validation that the consumer's age is above a requested minimum. This flow is carried out before the payment flow, which means that first the age verification is performed, then the consumer can continue to choose the payment method and make the payment. The minimum age of the consumer is sent as part of the request. Age Verification

Your Feedback

We would love to here from you! You can use this form to leave us feedback\requests.

Get Version

Returns the Cortina assembly version and build

Responses

Response samples

Content type
{
  • "ProductVersion": "string",
  • "Copyright": "string",
  • "ApiVersion": "string"
}

Post Start Session

Initial Request Validation

Request Body schema:
TokenId
string

3rd party Secret Token reference number

RandomNumber
string

Nayax will create 27 char Random Number

DynamicURL
string or null
  • Optional, support different url's.
  • Length: 255
  • Actor level url configuration
object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

Responses

Request samples

Content type
{
  • "TokenId": "string",
  • "RandomNumber": "string",
  • "DynamicURL": "string",
  • "CustomData": {
    }
}

Response samples

Content type
{
  • "TranIDCipher": "string",
  • "Status": {
    }
}

Post Sale End Notification

Optional method, Notify Sale Success, this method is called by Nayax to inform the integrator about a successful end of sale transaction.

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
DynamicURL
string or null
  • Optional, support different url's.
  • Length: 255
  • Actor level url configuration
object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "PaymentInfo": {
    },
  • "DynamicURL": "string",
  • "CustomData": {
    }
}

Response samples

Content type
{
  • "Status": {
    }
}

Cortina Age Verification

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "CustomData": {
    },
  • "ActorInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    }
}

Post Renew Key

Renew Key

Nayax Engine takes the key as is and asks the Provider MS to refresh the key (step 3) Cortina returns new PIN encryption key (step 4) under the ZMK of the provider Renew Key Process

Request Body schema:
object or null (BasicInfo)

Basic Information

object (CurrentKeyData)
  • Current Key Data

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "CurrentKeyData": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "NewKeyData": {
    }
}

Post Translate Callback

Translate Callback

Called by the Webhook Manager Service, this method returns a translated webhook to be processed in the Engine.

Request Body schema:
CallbackDt
string or null
PaymentProviderId
integer <int32>
ChannelId
integer <int32>
ProviderName
string or null
EndpointUrl
string or null
Payload
string or null
object (TranslatedCallback)

Responses

Request samples

Content type
{
  • "CallbackDt": "",
  • "PaymentProviderId": 19607,
  • "ChannelId": 1,
  • "ProviderName": "Adyen",
  • "EndpointUrl": "https://www.nayax.com/alternativeURL",
  • "Payload": "",
  • "TranslatedCallback": null,
  • "additionalProperties": false
}

Response samples

Content type
{
  • "Status": {
    }
}

Cortina Credit Card

Business Case

Credit Card Overview

This Section describes Credit Card transaction flow on Nayax Cortina V2, as well as API calls and parameters. Integrators (Payment Gateways) may use the Nayax Cortina Credit Card API to assure Credit Card payment via relevant Nayax devices such as VPOS Touch and Onyx. Credit Card Flow

Cortina Credit Card Flow

'Cortina Credit Card' is a flow in which an Credit Card card are use directly on the Nayax point of sale device in order to perform a transaction. Cortina Credit Card supports 2 types of transactions -

  • 'Pre-authorization' Flow
    • Authorization request - Nayax request to temporarily hold credit in the consumer account balance.
    • Settlement request – Nayax request to complete the transaction and to charge partial / full amount from the original authorization request.
  • 'Preselection' Flow
    • Sale Request - Nayax request to charge the consumer for a specific known amount in a single request.

Typical Success Scenarios

Pre-authorization

Transaction Flow

Preselection

Positive Preselection Scenario- (Non EMV or One Step EMV) Positive Preselection Flow Positive Preselection Scenario- (Two Steps EMV) If you don’t support sale and want to have 2 steps sale please contact your Integration Engineer

Typical Fail Scenarios

Pre-authorization

Typical Establish Security Failed Scenario - Start Session Failed

Start Session Failed

Typical Payment Decline Scenario - Authorization Failed

Authorization Failed

Typical Payment Decline Scenario - Authorization Declined

Authorization Declined

Typical Confused Consumer Scenario - Inactivity / Cancel /Invalid Choice

Confused Customer

Typical Vend Failure Scenario - Machine Dispense Failure

Machine dispense failure

Typical Payment Decline Scenario - Settlement Failed

Issues in settlement will be resolved by Nayax

Preselection

Typical Confused Consumer Scenario - Inactivity/Cancel/Invalid Choose

Failure after sale

Typical Establish Security Failed Scenario - Start Session Failed

Start Session Failed

Typical Payment Decline Scenario - Sale Failed

Sale request failed

Typical Vend Failure Scenario - Machine Dispense Failure

Machine Dispense failure

Typical Notification Failed Scenario - Sale End Notification Failed

Sale End Notification failure

Typical Payment Decline Scenario - Void Failed

Preselection Void failure

Decline Reasons Code List for Cortina Credit Card

The following list includes all the relevant codes for Cortina Credit Card:

  • 1 - Refer to card issuer
  • 2 - Refer to card issuer's special conditions
  • 3 - Invalid merchant
  • 4 - Pick-up
  • 5 - Do not honor
  • 6 - Error
  • 7 - Pick-up card, special condition
  • 8 - Honour with identification
  • 9 - Request in progress
  • 10 - Approved for partial amount
  • 11 - Approved (VIP)
  • 12 - Invalid transaction
  • 13 - Invalid amount
  • 14 - Invalid card number (no such number)
  • 15 - No such issuer
  • 16 - Approved, update track 3
  • 17 - Customer cancellation
  • 18 - Customer dispute
  • 19 - Re-enter transaction
  • 20 - Invalid response
  • 21 - No action taken
  • 22 - Suspected malfunction
  • 23 - Unacceptable transaction fee
  • 24 - File update not supported by receiver
  • 25 - Unable to locate record on file
  • 26 - Duplicate file update record, old record replaced
  • 27 - File update field edit error
  • 28 - File update file locked out
  • 29 - File update not successful, contact acquirer
  • 30 - Format error
  • 31 - Bank not supported by switch
  • 32 - Completed partially
  • 33 - Expired card
  • 34 - Suspected fraud
  • 35 - Card acceptor contact acquirer
  • 36 - Restricted card
  • 37 - Card acceptor call acquirer security
  • 38 - Allowable PIN tries exceeded
  • 39 - No credit account
  • 40 - Requested function not supported
  • 41 - Lost card
  • 42 - No universal account
  • 43 - Stolen card, pick-up
  • 44 - No investment account
  • 51 - Not sufficient funds
  • 52 - No checking account
  • 53 - No savings account
  • 54 - Expired card
  • 55 - Incorrect personal identification number
  • 56 - No card record
  • 57 - Transaction not permitted to cardholder
  • 58 - Transaction not permitted to terminal
  • 59 - Suspected fraud
  • 60 - Card acceptor contact acquirer
  • 61 - Exceeds withdrawal amount limit
  • 62 - Restricted card
  • 63 - Security violation
  • 64 - Original amount incorrect
  • 65 - Exceeds withdrawal frequency limit
  • 66 - Card acceptor call acquirer's security department
  • 67 - Hard capture (requires that card be picked up at ATM)
  • 68 - Response received too late
  • 75 - Allowable number of PIN tries exceeded
  • 90 - Cutoff is in process
  • 91 - Issuer or switch is inoperative
  • 92 - Financial institution or intermediate network facility cannot be found for routing
  • 93 - Transaction cannot be completed. Violation of law
  • 94 - Duplicate transmission
  • 95 - Reconcile error
  • 96 - System malfunction
  • 201 - Cardholder exceeded transaction amount limit
  • 202 - Provider general system failure
  • 203 - Request cannot be parsed (format error) by Provider
  • 204 - Provider did not receive mandatory parameters
  • 205 - Transaction is already refunded
  • 206 - Refund amount cannot be greater than original amount
  • 207 - Unknown Terminal ID
  • 990 - CertificateFileName not found
  • 991 - Failed to decipher message body
  • 992 - Timeout exception
  • 994 - Card Brand not supported
  • 996 - Transaction ID Unknown / Duplicate Transaction ID (Start Session Error)
  • 997 - Nayax did not receive mandatory parameters
  • 998 - Validation / request cannot be parsed
  • 999 - General exception
  • 1010 - Public Key Certificate not found
  • 1011 - Method not Implemented
  • 1012 - Cardholder exceeded daily / weekly / monthly transaction count limit
  • 1021 - Switch Interface

Technical Prerequisites

  • Cortina is a REST interface over HTTPS (TLS > V1.2) using JSON format for I/O.
  • Optional Site to Site VPN. If needed, it shall be discussed with the technical point of contact at Nayax.

Provided by Nayax to the Integrator

  • Secret Token (Token_Value, Token_ID) - Nayax provides an Integrator with a unique secret token (Secret Token Value and Secret Token ID) for communication.
  • From time-to-time Nayax may contact the integrator to replace the Token.
  • To download IP whitelisting (if needed) Press here
  • Nayax relevant POS devices.

Provided by Integrator to Nayax

  • The integrator shall provide Nayax with HTTPS URL access end points -
    • HTTPS URL - TEST environment
    • HTTPS URL - Production environment
  • The Integrator will provide Nayax its desired timeout in milliseconds -
    • range between [Int] 1000 – 15000, default value is 15000.
    • Immediate void settings - In case of T/O in authorization or settlement request, Nayax server shall perform by default 2 attempts to cancel/void the transaction with 30 seconds intervals between. For more details contact Nayax TPOC.
    • In preselection Transactions by default Nayax shall perform Sale end notification to inform the payment gateway (integrator) that the operator has completed the transaction successfully. For more details contact Nayax TPOC.
  • The Integrator will provide Nayax customize fields according to Nayax Hierarchy as needed.
    • Distributor > Operator > Direct Actor > Machine / Device.
  • The integrator shall provide Nayax with relevant testing Cards.
  • Brand certification shall be performed either by Nayax or by the Integrator (To be discussed during the business review).

Cortina Credit Card Authorization

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

Array of objects or null (Product)
object or null (ECom3DSInfo)
object or null (DukptInfo)
object or null (EncryptInfo)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    },
  • "EMVTags": {
    },
  • "ECom3DSResponseInfo": {}
}

Cortina Credit Card Settlement

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

Array of objects or null (Product)
object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (EncryptInfo)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    },
  • "Batch": {
    }
}

Cortina Credit Card Cancel

Request Body schema:
ReasonCode
integer <int16>
ReasonText
string or null
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (EncryptInfo)

Responses

Request samples

Content type
{
  • "ReasonCode": 0,
  • "ReasonText": "Unknown Error",
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    }
}

Cortina Credit Card Sale

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

Array of objects or null (Product)
object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (ECom3DSInfo)
object or null (DukptInfo)
object or null (EncryptInfo)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    },
  • "EMVTags": {
    },
  • "ECom3DSResponseInfo": {}
}

Cortina Credit Card Void

Request Body schema:
ReasonCode
integer <int16>
ReasonText
string or null
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (EncryptInfo)

Responses

Request samples

Content type
{
  • "ReasonCode": 50,
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    }
}

Cortina Credit Card Refund

Request Body schema:
ReasonCode
integer <int16>
ReasonText
string or null
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (EncryptInfo)

Responses

Request samples

Content type
{
  • "ReasonCode": 12,
  • "ReasonText": "Cashless Refunded by Operator",
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    }
}

Cortina Credit Card Incremental Auth

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

Array of objects or null (Product)
object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (EncryptInfo)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    },
  • "Batch": {
    }
}

Cortina Credit Card Inquiry3DS

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

Array of objects or null (Product)
object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (ECom3DSInfo)
object or null (DukptInfo)
object or null (EncryptInfo)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    },
  • "EMVTags": {
    },
  • "ECom3DSResponseInfo": {}
}

Cortina Prepaid

Business Case

External Prepaid Overview

This section describes Nayax Gateway External Prepaid V2 transaction flow, API calls and parameters. Integrators (Payment Gateways) can use the Nayax Cortina External Prepaid V2 API to confirm External Prepaid V2 payment on Nayax devices such as VPOS Touch and Onyx.

External Prepaid Flow

Cortina External Prepaid V2 Flow

'Cortina External Prepaid V2' is a flow in which an external prepaid card are use directly on the Nayax point of sale device in order to perform a transaction. Cortina External Prepaid V2 supports 2 types of transactions -

  • 'Pre-authorization' Flow
    • Authorization - Nayax requests to temporarily hold credit in the consumer’s account balance.
    • Settlement – Nayax requests to complete the transaction and to charge a partial / full amount from the original authorization request.
  • 'Preselection' Flow
    • Sale - Nayax requests to charge the consumer for a specific known amount in a single request.

Typical Success Scenarios

Pre-authorization

Transaction Flow 1

Preselection

Transaction Flow 2

Typical Fail Scenarios

Pre-authorization

Typical Establish Security Failed Scenario - Start Session Failed

Transaction Flow 3

Typical Payment Decline Scenario - Authorization Failed

Transaction Flow 4

Typical Payment Decline Scenario - Authorization Declined

Transaction Flow 5

Typical Confused Consumer Scenario - Inactivity/Cancel/Invalid Choice

Transaction Flow 6

Typical Vend Failure Scenario - Machine Dispense Failure

Manual Refund

Typical Payment Decline Scenario - Settlement Failed

Issues in settlement will be resolved by Nayax

Preselection

Typical Confused Consumer Scenario - Inactivity/Cancel/Invalid Choice

Transaction Flow 8

Typical Establish Security Failed Scenario - Start Session Failed

Transaction Flow 9

Typical Payment Decline Scenario - Sale Failed

Transaction Flow 10

Typical Vend Failure Scenario - Machine Dispense Failure

Transaction Flow 11

Typical Notification Failed Scenario - Sale End Notification Failed

Transaction Flow 12

Typical Payment Decline Scenario - Void Failed

Transaction Flow 13

Decline Reasons Code List for Cortina Cortina Prepaid

The following list includes all the relevant codes for Cortina Cortina Prepaid:

  • 1 - Insufficient funds
  • 2 - Transaction ID unknown
  • 3 - Cardholder exceeded daily / weekly / monthly transaction count limit
  • 4 - Cardholder exceeded transaction amount limit
  • 5 - Suspected Fraud
  • 6 - General system failure
  • 7 - Invalid amount
  • 8 - Request cannot be parsed (format error)
  • 9 - Transaction not allowed to cardholder
  • 40 - For Nayax internal use only.
  • 990 - CertificateFileName not found
  • 991 - Failed to decipher message body
  • 992 - Timeout exception
  • 994 - Card Brand not supported
  • 996 - Transaction ID Unknown / Duplicate Transaction ID (Start Session Error)
  • 997 - Missing mandatory parameters
  • 998 - Validation / request cannot be parsed
  • 999 - General exception
  • 1010 - Public Key Certificate not found
  • 1011 - Method not Implemented

Technical Prerequisites

  • Cortina is a REST interface over HTTPS (TLS > V1.2) using JSON format for I/O.
  • NOTE, Site to Site VPN is optional. If needed discuss with your technical point of contact at Nayax.

Provided by Nayax to the Integrator

  • Secret Token (Token_Value, Token_ID) - Nayax provides an Integrator with a unique secret token (Secret Token Value and Secret Token ID) for communication.
  • NOTE, From time-to-time Nayax may contact the integrator to replace the Token.
  • To download IP whitelisting (if needed) Press here
  • Optional - Nayax relevant POS devices.

Provided by Integrator to Nayax

  • HTTPS URL access endpoints -
    • HTTPS URL - TEST environment
    • HTTPS URL - Production environment
  • The Desired timeout in milliseconds ranges between [Int] 1000 – 15000, the default value is 15000 -
  • Immediate void settings- In case of T/O in authorization or settlement request, the Nayax server will perform 2 attempts to cancel/void the transaction with 30 seconds intervals between them, by default. For more details contact Nayax's technical point of contact.
  • In Preselection transactions by default Nayax will perform Sale end notification to inform the integrator (payment gateway) that the operator has completed the transaction successfully. For more details contact Nayax's technical point of contact.
  • Custom fields as needed, according to Nayax hierarchy - Distributor > Operator > Direct Actor > Machine / Device.
  • Relevant testing means. (e.g., card data (in stripe cards ), or physical test cards in other cases).
  • In case of a URL endpoint per different merchants, please provide a CSV file that contains a list of URLs per merchant ID, with, as a delimiter. For details please contact your Nayax technical point of contact regarding Dynamic URL.
  • Prepaid Card Format - please provide Nayax with the exact Format of your card.

Cortina Prepaid Authorization

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    },
  • "Balance": {
    }
}

Cortina Prepaid Settlement

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

Array of objects or null (Product)
object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "Products": [
    ],
  • "PaymentInfo": {
    },
  • "SecondaryDescription": "string"
}

Response samples

Content type
{
  • "Status": {
    },
  • "Balance": {
    }
}

Cortina Prepaid Cancel

Request Body schema:
ReasonCode
integer <int16>
ReasonText
string or null
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "ReasonCode": 999,
  • "ReasonText": "General exception",
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "Balance": {
    }
}

Cortina Prepaid Sale

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
Array of objects or null (Product)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    },
  • "Products": [
    ]
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    },
  • "Balance": {
    }
}

Cortina Prepaid Void

Request Body schema:
ReasonCode
integer <int16>
ReasonText
string or null
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "ReasonCode": 999,
  • "ReasonText": "General exception",
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    },
  • "Balance": {
    }
}

Cortina Prepaid Refund

Request Body schema:
ReasonCode
integer <int16>
ReasonText
string or null
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (CardData)

Additional data we read from the card (EMV data, expiration date, cvv2, etc.)

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "ReasonCode": 999,
  • "ReasonText": "General exception",
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "CardData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "Balance": {
    }
}

StaticQR

Business Case

Static QR Overview

This section describes the Nayax Gateway Static QR transaction flow, API calls and parameters. Integrators can use the Nayax Cortina Static QR API to process payment via Static QR payment on the following Nayax devices- VPOS Touch and Onyx. StaticQR Flow

Cortina Static QR Flow

Cortina 'Static QR' is a flow in which a fixed (Static) QR code is scanned to perform a transaction. Cortina Static QR supports 2 types of transactions -

  • 'Pre-authorization' transaction, with a 2-step flow
    • Authorization - Nayax requests to temporarily hold credit in the consumer account balance.
    • Settlement – Nayax requests to complete the transaction and to charge a partial / full amount from the original authorization request.
  • 'Preselection' transaction with a single step flow
    • Sale - Nayax requests to charge the consumer for a specific known amount in a single request.

Typical Success scenarios:

Pre-authorization

Transaction Flow

Preselection

Choosing a product on the vending machine

Transaction Flow

Choosing a product Via App (Remote Vend)

Transaction Flow

Typical Fail Scenarios

Pre-authorization

Typical Payment Decline Scenario - Authorization Failed

Transaction Flow

Typical Payment Decline Scenario - Settlement Failed

Transaction Flow

Typical Payment Decline Scenario - Machine Dispense Failure

Transaction Flow

Typical Vend Failed Scenario - Confused Consumer

Manual Refund

Typical Consumer Inactivity Scenario

Manual Refund

Preselection

Typical Payment Decline Scenario - Sale Failed

Transaction Flow

Typical Vend Failed Scenario - Machine Dispense Failure

Transaction Flow

Typical Vend Failed Scenario - Confused Consumer

Transaction Flow

Typical Vend Failed Scenario - Confused Consumer (option 2)

Manual Refund

Typical Device Failed Scenario - No Settlement

Manual Refund

Typical Consumer Inactivity Scenario

Manual Refund

Decline Reasons Code List for Cortina Cortina StaticQR

The following list includes all the relevant codes for Cortina Cortina StaticQR:

  • 1 - Insufficient funds
  • 2 - Transaction ID unknown
  • 3 - Cardholder exceeded daily / weekly / monthly transaction count limit
  • 4 - Cardholder exceeded transaction amount limit
  • 5 - Suspected Fraud
  • 6 - General system failure
  • 7 - Invalid amount
  • 8 - Request cannot be parsed (format error)
  • 9 - Transaction not allowed to cardholder
  • 20 - No VPN or MQTT enabled
  • 30 - Machine is not responding
  • 40 - For Nayax internal use only.
  • 50 - Unknown machine Id
  • 990 - CertificateFileName not found
  • 991 - Failed to decipher message body
  • 992 - Timeout exception
  • 994 - Card Brand not supported
  • 996 - Transaction ID Unknown / Duplicate Transaction ID (Start Session Error)
  • 997 - Missing mandatory parameters
  • 998 - Validation / request cannot be parsed
  • 999 - General exception
  • 1010 - Public Key Certificate not found
  • 1011 - Method not Implemented

Technical Prerequisites

  • Cortina is a REST interface over HTTPS (TLS > V1.2) using JSON format for I/O.
  • NOTE, Site-to-Site VPN is optional. If needed discuss with your technical point of contact at Nayax.

Provided by Nayax to the Integrator

  • Unique token (Secret Token Value and Secret Token ID) for two-sided communication.
    • From time-to-time Nayax may contact the integrator to replace the token.
  • To download IP whitelisting (if needed) Press here
  • Optional - Nayax relevant POS devices.

Provided by Integrator to Nayax

  • HTTPS URL access end points -
    • HTTPS TEST environment URL.
    • HTTPS Production environment URL.
  • Desired timeout in milliseconds - range between [Int] 1000 – 15000, default value is 1500.
  • Custom fields according to Nayax Hierarchy as needed.
  • Distributor > Operator > Direct Actor > Machine / Device.
  • Relevant testing means. (e.g., demi test accounts , demi cards, etc.).

Cortina StaticQR Start

This method starts every transaction flow and informs Nayax that a consumer has been approached to an operator's machine. This method is called by the Integrator and provides Nayax with a transaction Id (Generated by the integrator and binds all Nayax-Integrator communication regarding a certain transaction), AppUserID, TerminalId, secret token, and App account balance.

The request should be sent to the following address: https://lynx.nayax.com/payment/v2/transactions/cortina/(integrator's payment method name)/start

path Parameters
integratorName
required
string

Integrator name assigned by Nayax

Request Body schema:
AppUserId
string
  • Mandatory
  • Length: 40
  • Unique identifier of the consumer in Mobile App provider system
TerminalId
string
  • Conditional, must be sent if UniQR is not sent.
  • Length: 255
  • Unique Identifier for the vending machine printed on a sticker or encoded in the QR (HW-Serial of the device)
TransactionId
string
  • Mandatory
  • Length: 40
  • Unique identifier for the transaction which will be echoed in further requests and responses. Minimum of 8 chars.
SecretToken
string
  • Mandatory
  • Length: 64
  • Unique key for the your system. This value will be Provided by Nayax in advance. You should keep this value as a secret in your system.
UniQR
string or null
  • Conditional, must be sent if TerminalId is not sent.
  • Machine reference unique qr number
Balance
number or null <double>
  • Optional
  • Decimal (max 3 digits for cents)
  • The balance of user's account.
Array of objects or null (Product)
Data
string or null
  • Data received from a third party and will be sent back in response

Responses

Request samples

Content type
{
  • "AppUserId": 111111,
  • "TerminalId": 77788,
  • "TransactionId": 12345678,
  • "SecretToken": "43262a8f8136f704b3d42b3f116e4bb0c4bf69e6d3415aff6e2cb9dfe06630ff",
  • "Balance": 0
}

Response samples

Content type
{
  • "Status": {
    }
}

Cortina StaticQR Authorization

Used in preauthorization cases (e.g., when a consumer starts a transaction, but the exact clearing amount will be defined later according to their uses), this method is called by Nayax and provides the integrator with relevant information to validate and authorize an ongoing transaction by the consumer based on their account. /Authorization request will temporarily hold credit in the consumer account balance as part of the transaction flows. This command must be followed by either settlement or cancel request.

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (DeviceInfo)

Nayax Device Information

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    }
}

Cortina StaticQR Settlement

Upon successful dispense of a product/service by the operator's machine, Nayax will call this method to complete and capture the transaction with the integrator. This call will include the transaction’s final amount to be cleared by the integrator.

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (DeviceInfo)

Nayax Device Information

Array of objects or null (Product)
object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "Products": [
    ],
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    }
}

Cortina StaticQR Cancel

In events of revoking preauthorization process, this method is called by Nayax and provides the integrator with relevant information to revoke an ongoing instance of preauthorization transaction. Therefore, in such events this method (Cancel) will replace the settlement method and will release the temporarily captured credit in the consumer account. for example, in event such of Vend fail, authorization timeout, consumer manual cancels before choosing a product.

Request Body schema:
ReasonCode
integer <int16>
  • Optional
  • Cancellation reason code (by nayax system table of error codes)
ReasonText
string
  • Optional
  • Length: 255
  • Cancellation reason description (by nayax system table of error codes)
object or null (BasicInfo)

Basic Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (DeviceInfo)

Nayax Device Information

Responses

Request samples

Content type
{
  • "ReasonCode": 2,
  • "ReasonText": "Cashless cancelled by consumer",
  • "BasicInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    }
}

Cortina StaticQR Sale

Used in preselection cases (e.g., when a consumer starts a transaction, and the exact clearing amount is known), this method is called by Nayax and provides the integrator with relevant information to charge the consumer account balance for a specific amount in a single request.

Request Body schema:
object or null (BasicInfo)

Basic Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (DeviceInfo)

Nayax Device Information

Array of objects or null (Product)

Mandatory Products details

Responses

Request samples

Content type
{
  • "ReasonCode": 0,
  • "ReasonText": "string",
  • "BasicInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "Products": [
    ]
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    }
}

Cortina StaticQR Void

This method is called by Nayax to void a previously successful payment request. For example, in cases such as vend failed, Cortina time out in /sale method, and device failed to produce settlement after a successful /Sale. Although in pre-selection cases /Void may resemble to /Refund method, /Void should always be implemented as it addresses different use cases.

Request Body schema:
ReasonCode
integer <int16>
  • Optional
  • Cancellation reason code (by nayax system table of error codes)
ReasonText
string
  • Optional
  • Length: 255
  • Cancellation reason description (by nayax system table of error codes)
object or null (BasicInfo)

Basic Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (DeviceInfo)

Nayax Device Information

Responses

Request samples

Content type
{
  • "ReasonCode": 0,
  • "ReasonText": "string",
  • "BasicInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    }
}

Cortina StaticQR Refund

This method is called by Nayax, within Nayax web system (DCS), to refund full/partial amount of the sale/settlement payment requests or a successful inquiry, for example due to an Application user’s complaint.

Request Body schema:
ReasonCode
integer <int16>
  • Optional
  • Refund reason code (by nayax system table of error codes)
ReasonText
string
  • Optional
  • Length: 255
  • Refund reason description (by nayax system table of error codes)
object or null (BasicInfo)

Basic Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "ReasonText": "string",
  • "BasicInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    }
}

DynamicQR

Business Case

Dynamic QR Overview

This section describes the Nayax Gateway Dynamic QR transaction flow, including API calls and parameters. The Nayax Cortina Dynamic QR API can be used to process payments on the following Nayax devices- VPOS Touch and Onyx. DynamicQR Flow

Cortina Dynamic QR Flow

'Dynamic QR' is a flow where each transaction has its own unique QR code that is generated and displayed for the application user to scan, in order to process the payment. Cortina Dynamic QR currently supports a ‘Preselection’ flow. Preselection is a one-step transaction flow where Nayax requests to charge the Application User a pre-known amount in a single request. Transaction Flow

Typical Fail Scenarios:

Transaction Flow Typical Payment Declined

Transaction Flow

Transaction Flow Typical Vend Fail

Transaction Flow

Transaction Flow Typical Time Out

Transaction Flow

Manual Refund / Auto Void

Manual Refund

Decline Reasons Code List for Cortina Cortina DynamicQR

The following list includes all the relevant codes for Cortina Cortina DynamicQR:

  • 1 - Insufficient funds
  • 2 - Transaction ID unknown
  • 3 - Cardholder exceeded daily / weekly / monthly transaction count limit
  • 4 - Cardholder exceeded transaction amount limit
  • 5 - Suspected Fraud
  • 6 - General system failure
  • 7 - Invalid amount
  • 8 - Request cannot be parsed (format error)
  • 9 - Transaction not allowed to cardholder
  • 20 - No VPN or MQTT enabled
  • 30 - Machine is not responding
  • 40 - For Nayax internal use only.
  • 50 - Unknown machine Id
  • 990 - CertificateFileName not found
  • 991 - Failed to decipher message body
  • 992 - Timeout exception
  • 994 - Card Brand not supported
  • 996 - Transaction ID Unknown / Duplicate Transaction ID (Start Session Error)
  • 997 - Missing mandatory parameters
  • 998 - Validation / request cannot be parsed
  • 999 - General exception
  • 1010 - Public Key Certificate not found
  • 1011 - Method not Implemented

Technical Prerequisites

  • Cortina is a REST interface over HTTPS (TLS > V1.2) using JSON format for I/O.
  • NOTE, Site-to-Site VPN is optional. If needed discuss with your technical point of contact at Nayax.

Provided by Nayax to the Integrator

  • Integrators are given a unique token (Secret Token Value and Secret Token ID) for two-sided communication.
  • NOTE, From time-to-time Nayax may contact the integrator to replace the token.
  • Nayax will provide the integrator with a test POS device

Provided by Integrator to Nayax

  • In order to utilize the Cortina API, integrators need to provide Nayax with the following.
  • HTTPS URL access points -
    • Https TEST environment URL.
    • Https Production environment URL.
  • In case of multiple payment channels (under the same dynamic QR), the integrator will provide the following attributes -
    • Channel ID (string NameOfChannel) that will be in the route of the API call- / GenerateQR/ NameOfChannel.
    • Channels' logos (JPEG ChannelImage), that will be shown on the Nayax device screen.
    • Desired timeout in milliseconds, range between [Int] 1000 – 15000..
    • Desired polling settings configurations-
    • QR Polling Timeout Milliseconds, range between [Int] 60000 – 180000.
    • QR Polling Attempts, range between [Int] 1 – 100 .
    • QR Interval Polling delay, range between [Int] 1000 – 15000.
    • Custom API fields needed to integrate.
    • Relevant testing means. (e.g; demi test accounts, demi cards, etc.).

Cortina DynamicQR GenerateQR

This method is called by Nayax and provides the integrator with a transaction Id identification (Generated in /StartSession), required Amount, merchant, and Machine details (and more). The integrator Shall validate the information and respond with the Dynamic QR information to be displayed on the Nayax device accordingly.

Request Body schema:
ChannelId
integer or null <int32>
  • Conditional, for Multi-channel integration, Contact Nayax TPOC to define.
  • Channel Values shall be provided by Nayax, and cannot be altered.
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

Array of objects or null or null (Product)
object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "ChannelId": 19,
  • "BasicInfo": {
    },
  • "DeviceInfo": null,
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "Product": [
    ]
}

Response samples

Content type
{
  • "QRCode": "DynamicQrResponse_QRCode_Test",
  • "QRData": {
    },
  • "Status": {
    },
  • "additionalProperties": false
}

Cortina DynamicQR Inquiry

This method is called by Nayax to inquire the approval status of a Transaction ID. This call will include the transaction’s final amount and the transaction ID generated in the /GenerateQR call. An “Approved” response this call will usually attempt to vend/release the product. A “Decline” will terminate the transaction and a “Pending” response will trigger a subsequent /Inquiry request after a predefined time. Consult your Technical Point of Contact in Nayax to setup how many calls and how frequently should they be polled.

Request Body schema:
object or null (BasicInfo)

Basic Information

Array of objects or null (Product)
object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)
object or null (Polling)

Responses

Request samples

Content type
{
  • "BasicInfo": {
    },
  • "Products": [
    ],
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "PaymentInfo": {
    },
  • "Polling": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    }
}

Cortina DynamicQR Refund

This method is called by Nayax, within Nayax web system (DCS), to refund full/partial amount of the sale/settlement payment requests or a successful inquiry, for example due to an Application user’s complaint.

Request Body schema:
ReasonCode
integer <int16>
  • Optional
  • length: Short integer (16)
  • Refund reason code as saved in Nayax system
ReasonText
string or null
  • Optional
  • length: 64
  • Refund description as saved in Nayax system
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "ReasonCode": 0,
  • "ReasonText": "string",
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    }
}

Cortina DynamicQR Void

This method is called by Nayax to void a previously successful Inquiry payment requests (for example- in cases where product was not dispensed, or the machine has been timed-out). In some cases, this command may resemble the ‘effect’ of /Refund (in pre-selection cases) method. However, the /Void method should always be implemented nevertheless as it refers to a dedicated user story.

Request Body schema:
ReasonCode
integer <int16>
  • Optional
  • length: Short integer (16)
  • Refund reason code as saved in Nayax system
ReasonText
string or null
  • Optional
  • length: 64
  • Refund description as saved in Nayax system
object or null (BasicInfo)

Basic Information

object or null (DeviceInfo)

Nayax Device Information

object or null (MachineInfo)

Machine Information

object or null (ActorInfo)

Merchant (aka: Actor) Information.

object or null (CustomData)

Custom Fields Information, Contact Nayax TPOC to define.

object or null (PaymentInfo)
  • This Object Identifies Transaction Information and references (RRNs,Transaction IDs, AUth Code, original amounts etc..)
  • The Object is Included in all response messages for Payment calls
  • When included in requests (cases of /Settlement, /Void, /Refund, and /Inquiry) the object refers to the PaymentInfo object returned on a previous call (e.g a Refund request will include the information returned in the Original /Sale, /Settlement or /Inquiry responses the settled it.)

Responses

Request samples

Content type
{
  • "ReasonCode": 3,
  • "ReasonText": "Cashless Cancelled by machine",
  • "BasicInfo": {
    },
  • "DeviceInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "CustomData": {
    },
  • "PaymentInfo": {
    }
}

Response samples

Content type
{
  • "Status": {
    },
  • "PaymentInfo": {
    }
}

Cortina Onboarding

Cortina Onboarding Actor Overview

When an operator adds a relevant payment provider that requires auto onboarding. This allows the payment provider to receive the relevant DCS 'Actors' information as defined in the Nayax system.

Cortina Onboarding Machine Overview

Business Case

When an operator adds a relevant payment provider that requires auto onboarding. This allows the payment provider to receive the relevant DCS 'Machines' information as defined in the Nayax system.

Get Version

Returns the Commerce assembly version and build

Responses

Response samples

Content type
{
  • "ProductVersion": "string",
  • "Copyright": "string",
  • "ApiVersion": "string"
}

Onboard Actor

Request Body schema:
object or null (OnboardingBasicInfo)

Describing the onboarding Operation details

object or null (OnboardActorInfo)

Actor info for onboarding

object or null (OnboardOperatorInfo)

Operator info for onboarding

object or null (OnboardDistributorInfo)

Distributor info for onboarding

UpdateInfo
Array of strings or null (OnboardUpdateInfo)
object or null (OnboardCustomData)

Custom Fields Information, Contact Nayax TPOC to define.

Responses

Request samples

Content type
{
  • "OnboardingBasicInfo": {
    },
  • "ActorInfo": {
    },
  • "OperatorInfo": {
    },
  • "DistributorInfo": {
    },
  • "UpdateInfo": [
    ],
  • "CustomData": {
    }
}

Response samples

Content type
{
  • "OnboardStatus": {
    },
  • "ActorOnboardingData": {
    }
}

Onboard Machine

Request Body schema:
object or null (OnboardingBasicInfo)

Describing the onboarding Operation details

object or null (OnboardMachineInfo)

Machine info for onboarding

object or null (OnboardActorInfo)

Actor info for onboarding

object or null (OnboardOperatorInfo)

Operator info for onboarding

object or null (OnboardDistributorInfo)

Distributor info for onboarding

UpdateInfo
Array of strings or null (OnboardUpdateInfo)
object or null (OnboardCustomData)

Custom Fields Information, Contact Nayax TPOC to define.

Responses

Request samples

Content type
{
  • "OnboardingBasicInfo": {
    },
  • "MachineInfo": {
    },
  • "ActorInfo": {
    },
  • "OperatorInfo": {
    },
  • "DistributorInfo": {
    },
  • "UpdateInfo": [
    ],
  • "CustomData": {
    }
}

Response samples

Content type
{
  • "OnboardStatus": {
    },
  • "MachineOnboardingData": {
    }
}