Event Callbacks

The SDK triggers event callbacks in the EMV Core SDK to notify the application of specific events during the transaction lifecycle. They enable developers to respond dynamically to changes in transaction status and system events. These callbacks provide real-time updates, keeping the SDK and the application in sync. These are the available callbacks.

CardTokenReceived
IncrementalAuthorizationResponse
ReaderMessageEvent
SystemStatusChanged
TransactionComplete

You can read a more detailed description of each Callback event in the sections below.

`CardTokenReceived`

This event is triggered after a card token is successfully retrieved.

JSON
Android
Linux

Open loop example:

{"jsonrpc":"2.0", "method": "CardTokenReceived", "params": {"status": "OK",
"errorCode": 0, "errorDescription": "", "CardToken":
"WSAr79nKPywW3INXrWvr6IL3vgTgSJlwZBgseKDmMHM=", "PartialPan": "",
"CardType": "EMV"}, "id": 702}

Closed loop example:

{"jsonrpc":"2.0", "method": "CardTokenReceived", "params": {"status":
"LocalCLP", "errorCode": 0, "errorDescription": "", "CardToken": "73D0D1C5",
"PartialPan": "", "CardType": "Type A"}, "id": 702}

Parameters:

Parameter	Description
`status`	Transaction result: `OK`, `Declined`, `Error`, `Timeout`, `Cancelled`, or `LocalCLP`.
`errorCode`	Numerical error code. `0` when there is no error.
`CardToken`	Card token. Base64 string for payment cards, or the card UID for closed loop (Mifare) cards.
`PartialPan`	Masked PAN with the card account number’s first six and last four digits. Empty for closed loop cards.
`CardType`	Card scheme (for example, EMV, MasterCard, Visa). For closed loop cards, the card technology (for example, Type A, Mifare).

Java

void CardTokenReceived(TokenDetails tokenDetails);

Where tokenDetails has two fields:

Parameter	Description
`CardToken`	Base64 string for payment cards, or the card UID for closed loop (Mifare) cards.
`CardType`	Card scheme (for example, EMV, MasterCard, Visa). For closed loop cards, the card technology (for example, Type A, Mifare).

Linux

void LibOtiKiosk_Register_GetTokenResponse_Callback(GetTokenCb_t cb);

Parameters:cb: A callback function of type void (*)(otiKioskGetTokenResponse* resp). This function is triggered automatically when a card token operation completes.The callback receives a pointer to an otiKioskGetTokenResponse struct with the token result:

typedef struct {
    otiTransactionStatus status;        // Operation status
    int error_code;                      // Error code if failed
    char error_message[100];             // Error description
    char card_token[128];                // Generated card token
    char card_type[32];                  // Card scheme (e.g., EMV, Visa, Mifare)
} otiKioskGetTokenResponse;

Struct fields:

Field	Description
`status`	Status of the token operation. Same values as the JSON `status` field.
`error_code`	Numerical error code. `0` when there is no error.
`error_message`	Short technical description of the error, for developer and support use. Do not display to users.
`card_token`	Generated card token. Base64 string for payment cards, or the card UID for closed loop cards.
`card_type`	Card scheme (for example, EMV, Visa) for payment cards, or card technology (for example, Type A, Mifare) for closed loop cards.

`IncrementalAuthorizationResponse`

This event is only available for the Android operating system.

The IncrementalAuthorizationResponse event triggers when an IncrementalAuthorization call completes, whether it succeeds or fails. It’s reserved for a future multi-step flow and isn’t required today: for the current single-step behavior, see Single-step incremental authorization.

Nayax doesn’t yet support the multi-step flow server-side. IncrementalAuthorizationResponse won’t fire beyond what’s described above.

Java

void IncrementalAuthorizationResponse(IncrementalAuthorizationDetails details);

Parameter	Description
`Status`	`OK` or `Error`.
`Amount`	The incremental amount, in major units (for example, 1.50 for $1.50).
`TransactionReference`	Transaction reference from the original `IncrementalAuthorization` call.

`ReaderMessageEvent`

This callback provides updates on user interface messages from the card reader.

JSON
Android
Linux

{"jsonrpc": "2.0", "method": "ReaderMessageEvent", "params": {"index": 36,
"line1": "Authorizing", "line2": "Please wait"}}

Parameter	Description
index	The index of the message. Decimal value according to the Message Index table. Note: The actual text presented on the reader display depends on the Kiosk configuration and may differ from the table values.

Java

public ReaderMessage(int index, String line1, String line2)

Parameters:

Parameter	Description
`index`	The index of the message. Decimal value according to the Reader messages Index table.
`line1`	Text is shown on the 1st line of the reader display.
`line2`	Text is shown on the 2nd line of the reader display.

Reader ConfigurationFor this feature to work, the reader must be configured to send External Display message events (Tag DF 46 with index 04).

Linux

void on_reader_event(uint8_t msg_index, char* line1, char* line2) {
printf("Reader Display: %s | %s\n", line1, line2);
}
LibOtiKiosk_Register_ReaderEvent_Callback(on_reader_event);

`SystemStatusChanged`

This event is only available for the Android operating system.

The SystemStatusChanged event indicates changes in the SDKs or connected devices’ operational state.

Java

void SystemStatusChanged(EmvCoreStatus emvCoreStatus);

EmvCoreStatus is an enumeration representing the current state of the system. See the possible result values in the table below:

Result	Description
`NotReady`	The SDK is not operational.
`Ready`	The SDK is ready for transactions.
`PaymentTransaction`	A transaction is currently in progress.
`Update`	A firmware or configuration update is ongoing.
`NoReader`	No card reader is currently connected.
`NoTerminalId`	Indicates the EMV Core does not have a configured Terminal ID.
`NoNetwork`	No network connection is available.
`NoTransaction`	No transaction is currently in progress or was found.

`TransactionComplete`

EMV Core calls TransactionComplete when a transaction completes, whether it succeeds or fails. It gives your application the details needed to print a receipt and link transactions to sale events (for example, in a dispute).

JSON
Android
Linux

Open loop request:

JSON

{
  "jsonrpc": "2.0",
  "method": "TransactionComplete",
  "params": {
    "status": "OK",
    "errorCode": 0,
    "errorDescription": "",
    "transactionId": "2046651064",
    "authorizationDetails": {
      "AmountAuthorized": 4.50,
      "AmountRequested": 4.50,
      "AuthorizationCode": "",
      "PartialPan": "541333******4111",
      "CardType": "MasterCard",
      "IsTransactionApproved": true,
      "eReceipt": "https://s.wee.ai/tr/...eIHT",
      "Card_ID": "",
      "Card_Balance": 0.00,
      "RRN": "",
      "TransactionDbID": "2046651064",
      "Transaction_Referance": "2046651064",
      "CardToken": "5VXkNqtUDJBxQj9p/qTGt74jWaPHlRs7xxWa1Yu0gDI=",
      "Additional_Parameters": {
        "hwSerial": "0207122525168550",
        "SiteId": "6",
        "AllowFundsOverAuthAmount": "false",
        "IncrementalMaxDefaultCredit": "450.0",
        "EntryMode": "4",
        "MachineAuTime": "2026-05-10T16:53:39.017",
        "NayaxTransactionId": "6811150712"
      }
    }
  },
  "id": 701
}

Closed loop request with mifare_read:To use mifare_read, set the Mifare Blocks to Read attribute in Nayax Core under Embedded Advanced. The following example uses KA01B10B14 to read block 1 with key A, and blocks 10 and 14.

JSON

{
  "jsonrpc": "2.0",
  "method": "TransactionComplete",
  "params": {
    "status": "LocalCLP",
    "errorCode": 0,
    "errorDescription": "",
    "transactionId": "4701113B",
    "authorizationDetails": {
      "CardType": "Mifare",
      "Card_ID": "4701113B",
      "Card_Balance": 0.00,
      "CardToken": "4701113B",
      "Additional_Parameters": {}
    }
  },
  "mifare_read": {
    "UID": "4701113B",
    "B10": "00000000000000000000000000000000",
    "B14": "00000000000000000000000000000000"
  },
  "id": 701
}

Response:

JSON

{"jsonrpc":"2.0", "result":true, "id":701}

Parameters:

Parameter	Description
id	Command ID.
status	Transaction result: `OK`, `Declined`, `Error`, `Timeout`, `Cancelled`, `LocalCLP`, or `PollContinuous`.
errorCode	Numerical error code. `0` when there is no error.
errorDescription	Short technical description of the error, for developer and support use. Do not display to users.
transactionId	Transaction ID. Use this value in `ConfirmTransaction` or `VoidTransaction`.
authorizationDetails	Authorization details including amount authorized, amount requested, authorization code, partial PAN, card type, approval status, and card token.
Additional_Parameters	Optional data from the PSP in `{"fieldName": "fieldValue"}` format. Use these values for Nayax External Settlement (Remote Settlement).
mifare_read	Block data read from the Mifare card, based on the `CLP_MIFARE_READ` attribute. Empty when absent.

Java

void TransactionComplete(AuthorizationDetails authorizationDetails);

In case of no responseIf EMV Core doesn’t get an answer, it will re-send 2 times (for a total of 3 messages), and if it still doesn’t get an answer, it will assume the message received and will not cancel the transaction.

Where:

Parameter	Description
`errorDescription`	A short technical description of the error intended to help developers and tech support personnel identify the problem. It should not be presented to users.
`errorCode`	A numerical code describing the error if one occurs. See the table below for details on each code.
`status`	Possible statuses: OK, Declined, Error, Timeout, Cancelled, LocalCLP, PollContinuous.
`amountAuthorized`	Amount approved for the transaction in major units (for example, dollars, not cents). May be lower than the original request if the card is prepaid.
`amountRequested`	Amount requested for transaction approval in major units (for example, dollars, not cents).
`authorization_Code`	PSP Transaction Identifier issued for approved transactions (EVO, Apriva, Traderoot).
`partialPan`	Masked PAN with the card account number’s first six and last four digits.
`cardType`	Card scheme (MasterCard, Visa, Amex, and others). For closed-loop cards, the card technology type. See the closed loop card types table below.
`authID`	Approval Code from the processor (for some processors).
`receiptID`	Digital receipt ID in the PSP System.
`TransactionID`	Transaction ID. Use this value in `ConfirmTransaction` or `VoidTransaction`.
`Transaction_Reference`	Transaction reference. Use this value in `ConfirmTransaction` or `VoidTransaction`.
`TransactionDbID`	Deprecated. Use `TransactionID` instead.
`RRN`	Processor reference number for approved transactions.
`card_ID`	Mifare UID in case of a Mifare card and `CLP_MIFARE_ENABLED=2`.
`isTransactionApproved`	Boolean indicating the transaction approval status.
`eReceipt`	URL for the Nayax eReceipt. See eReceipt settings in Nayax Core for required configuration.
`CardToken`	A token identifying the card. For payment cards, it returns a Base64 string. For closed-loop cards (for example, Mifare), it returns the card UID.
`Channel`	Channel used for card reading (for example, Contactless, Magstripe, Contact).
`AID, TVR, IAD, TSI, ARC`	Card/Transaction parameters that may be used for the receipt.
`transactionTime`	Transaction time.
`application_Label`	Card scheme (for example, Visa, MasterCard, American Express).
`currency`	Currency code according to ISO 4217 (for example, 840 means US dollars).
`CVM`	Card Verification Method.
`additional_Parameters`	Optional additional parameters from the payment processor. Used for Nayax External Settlement (Remote Settlement). Includes: `SiteId`, `EntryMode`, `MachineAuTime`, `NayaxTransactionId`, `hwSerial`, `AllowFundsOverAuthAmount`, and `IncrementalMaxDefaultCredit`.
`hwSerial`	Hardware serial number of the terminal.
`AllowFundsOverAuthAmount`	Whether incremental charges above the authorized amount are permitted (`"true"` or `"false"`).
`IncrementalMaxDefaultCredit`	Maximum credit amount allowed for incremental authorization.
`card_Balance`	Card balance for closed-loop cards managed by Nayax.
`mifare_read`	Optional. JSON with the results of Mifare blocks read, according to the `CLP_MIFARE_READ` configuration attribute. Empty string when not configured. Returns a JSON object keyed by UID and by block number (for example, `B10`, `B14`).

`TransactionComplete` Closed loop card types

The following card technology types may be returned in the cardType field for closed-loop transactions.

Card Type	Description
`Type A`	ISO/IEC 14443 Type A
`Type B`	ISO/IEC 14443 Type B
`Mifare`	Mifare
`Mifare-U`	Mifare Ultralight
`DesFire`	Mifare DESFire
`Mifare-P`	Mifare Plus
`Vicinity`	ISO/IEC 15693
`Vicinity-P`	ISO/IEC 15693 HID iClass
`Felica`	FeliCa JIS X 6319-4

`TransactionComplete` Error codes

These are the possible error codes in the response:

Error Type	Error Code
JsonParse	-1
General	-1
Terminate	-1
Timeout	-1
Transaction Declined	-1
Positive code	Payment Service Provider (PSP) errors

Linux

void on_transaction_complete(otiKioskPaymentResponse* resp) {
if (resp->status == otiTransactionStatus_OK) {
printf("Transaction successful: %s\n", resp->transaction_reference);
} else {
printf("Transaction failed: %s\n", resp->error_message);
}
}
LibOtiKiosk_Register_TransactionComplete_Callback(on_transaction_complete);

Parameters:cb: A callback function of type void (*)(otiKioskPaymentResponse* resp). This function is triggered automatically when a transaction reaches a final state.The callback receives a pointer to an otiKioskPaymentResponse struct with the full transaction result:

typedef struct {
    otiTransactionStatus status;        // Transaction status
    int error_code;                      // Error code if failed
    char error_message[100];             // Error description
    double amount_requested;             // Requested amount
    double amount_authorized;            // Authorized amount
    char transaction_reference[128];     // Unique transaction reference
    char partial_PAN[20];                // Masked card number
    char card_type[32];                  // Card type (Visa, MasterCard, etc.)
    char card_id[32];                     // Card identifier
    char card_token[128];                // Secure card token
    char EReceipt[256];                   // Electronic receipt URL
    char Additional_Parameters[256];      // Additional parameters, used for remote settlement
    double card_balance;                  // RFU: card balance for closed-loop cards
    bool is_transaction_approved;         // Approval status
    char authorization_code[128];         // PSP authorization code
    char rrn[128];                         // Processor reference number
    NayaxTransactionIdInfo nayax_info;    // Fields for remote settlement
    char mifare_read[256];                // Raw JSON of mifare_read params for CLP_MIFARE_READ, empty when absent
} otiKioskPaymentResponse;

Struct fields:

Field	Description
`status`	Transaction status. Same values as the JSON `status` field.
`error_code`	Numerical error code. `0` when there is no error.
`error_message`	Short technical description of the error, for developer and support use. Do not display to users.
`amount_requested`	Amount requested for transaction approval, in major units (for example, dollars, not cents).
`amount_authorized`	Amount approved for the transaction, in major units. May be lower than the requested amount for prepaid cards.
`transaction_reference`	Transaction ID. Use this value in `ConfirmTransaction` or `VoidTransaction`.
`partial_PAN`	Masked PAN with the card account number’s first six and last four digits.
`card_type`	Card scheme for open-loop cards, or card technology for closed-loop cards.
`card_id`	Mifare UID when the card is a Mifare card and `CLP_MIFARE_ENABLED=2`.
`card_token`	Token identifying the card. Base64 string for payment cards, or the card UID for closed-loop cards.
`EReceipt`	URL for the Nayax eReceipt. See eReceipt settings in Nayax Core below.
`Additional_Parameters`	Optional data from the PSP, used for Nayax External Settlement (Remote Settlement).
`card_balance`	RFU. Card balance for closed-loop cards managed by Nayax.
`is_transaction_approved`	Whether the transaction was approved.
`authorization_code`	PSP transaction identifier issued for approved transactions.
`rrn`	Processor reference number for approved transactions.
`nayax_info`	Fields required for Nayax External Settlement (Remote Settlement).
`mifare_read`	Raw JSON of the blocks read from a Mifare card, based on the `CLP_MIFARE_READ` attribute. Empty when absent.

For the full closed-loop card type list and error code list, see the equivalent fields in the Android tab above.

eReceipt settings in Nayax Core

To receive eReceipts, configure the operator in Nayax Core with the following settings.

Configure VAS provider settings

In the operator settings, go to the VAS Provider tab. Under eReceipt Platform, enter the Provider Name and Business ID.

Operator VAS Provider tab showing eReceipt Platform with Provider Name and Business ID fields

Update machine payment options

In the machine settings, go to the Payment tab. Under Transaction Options, uncheck Enable eReceipt on Transaction end.

Machine Payment tab showing Enable eReceipt on Transaction end checkbox under Transaction Options

EMV Core Guides

Android & Linux SDK

RTOS SDK

UNO-mini Hardware

EMV Core Release Notes

`CardTokenReceived`

`IncrementalAuthorizationResponse`

`ReaderMessageEvent`

`SystemStatusChanged`

`TransactionComplete`

`TransactionComplete` Closed loop card types

`TransactionComplete` Error codes

eReceipt settings in Nayax Core

​CardTokenReceived

​IncrementalAuthorizationResponse

​ReaderMessageEvent

​SystemStatusChanged

​TransactionComplete

​TransactionComplete Closed loop card types

​TransactionComplete Error codes

​eReceipt settings in Nayax Core

`CardTokenReceived`

`IncrementalAuthorizationResponse`

`ReaderMessageEvent`

`SystemStatusChanged`

`TransactionComplete`

`TransactionComplete` Closed loop card types

`TransactionComplete` Error codes

eReceipt settings in Nayax Core