The EMV Core SDK provides robust APIs for managing payment transactions. These APIs enable seamless integration of cashless payment functionality into applications, supporting both open- and closed-loop systems. The SDK ensures secure, efficient, and flexible payment handling while offloading complexities to the Nayax backend.
The methods available for payment management are:
The sections below describe them in more detail.
CancelTransaction
The CancelTransaction method stops the execution of an ongoing PayTransaction or PreAuthorize call. The system blocks further requests until the cancellation is accepted and confirmed.
Implementation Notes:
- Before Card Presentation: If a card has not been presented yet, the Reader poll sequence stops. The display will show “Cancelling”; the host application must then update the UI using the
ShowMessage command.
- During Processing: If the card was already presented but processing is not finished, the system returns
CannotCancel. It may take a few seconds to receive the TransactionComplete event while the EMV Core waits for the online result.
- After Completion: If the transaction is already finished, it returns
NoTransaction.
- Undoing Success: To undo a completed transaction, use
VoidTransaction.
- Declined Transactions: If
TransactionComplete returns a Decline status, there is no need to send a VoidTransaction command.
- Events: In all scenarios, EMV Core will eventually send a
TransactionComplete event to finalize the state.
See the API Signature for the CancelTransaction method:
Request: {"jsonrpc": "2.0", "method": "CancelTransaction", "id": 802}
{"jsonrpc": "2.0", "result": true, "id": 802}
void CancelTransaction();
KIOSK_RET LibOtiKiosk_CancelTransaction(void);
If the card has already been presented and processed, the system will return a CannotCancel error.
ConfirmTransaction
A confirmation request is the second stage of an authorization request. It is used to confirm the authorization obtained so that settlement can proceed.
API Signature
Response:{
"jsonrpc": "2.0",
"method": "TransactionComplete",
"params": {
"status": "OK",
"errorCode": 0,
"errorDescription": "",
"transactionId": "6103587330",
"authorizationDetails": {
"AmountAuthorized": 4.5,
"AmountRequested": 4.5,
"AuthorizationCode": "AuthOK",
"PartialPan": "541333******4111",
"CardType": "MasterCard",
"IsTransactionApproved": true,
"eReceipt": "",
"Card_ID": "2025-11-25 14:35:39.140|6|3",
"Card_Balance": 0.0,
"RRN": "251125123539",
"TransactionDbID": "6103587330",
"Transaction_Referance": "6103587330",
"CardToken": "5VXkNqtUDJBxQj9p/qTGt74jWaPHlRs7xxWa1Yu0gDI=",
"Additional_Parameters": {
"SiteId": "6",
"EntryMode": "4",
"MachineAuTime": "2025-11-25T14:35:38.885",
"NayaxTransactionId": "6103587330"
}
}
},
"id": 701
}
{"jsonrpc":"2.0","method":"ConfirmTransaction", "params": {"amount":450,
"fee":0, "productID":42, "transaction_Reference":"6103587330"}, "id":8}
{"jsonrpc":"2.0", "result":true, "id":8}
| Parameter | Description |
|---|
| id | Command ID. |
| amount | The actual amount to charge – in minor units (cents). |
| transactionReference | Transaction reference from the PSP. Use the TransactionDbID field from the TransactionComplete event. |
| productID | Optional parameter: ID of the product selected by the consumer. This number will be saved on the server and available for reports. |
| terminal_data | Optional parameter: terminal_data=(key1=value1,key2=value2). |
void ConfirmTransaction(String transactionReference, int actualAmountMinorUnits, int productID) throws EmvCoreException;
| Parameter | Description |
|---|
transactionReference | Unique reference from pre-authorization. |
actualAmountMinorUnits | The final amount for settlement. |
productID | Product identifier. |
KIOSK_RET LibOtiKiosk_ConfirmTransaction(uint32_t amount_cents, uint32_t fee_cents, uint32_t product_id, char* transaction_reference);
| Parameter | Description |
|---|
amount_cents | Amount to charge in minor units (cents, not dollars). |
fee_cents | Optional fee amount in minor units. |
transaction_reference | Unique reference from pre-authorization. |
product_id | Product identifier. |
GetCardToken
The GetCardToken method initiates the card tokenization process, returning a card token without performing a financial transaction.
EMV Core waits for a card to be presented, reads the data, and triggers a CardTokenReceived event:
- Payment Cards: Returns a Base64 string containing the card token.
- CLP Cards (e.g., Mifare): Returns the card UID.
API Signature
Request:{
"method": "GetCardToken",
"params": {
"continuous": false,
"timeout": 60
},
"id": 5820
}
{"jsonrpc": "2.0", "result": true, "id": 5820}
| Parameter | Description |
|---|
| timeoutSeconds | Maximum number of seconds to wait. If no card arrives within this time – return Timeout status. Maximum value is 60 seconds. |
void GetCardToken(int timeoutSeconds, boolean continuous) throws EmvCoreException;
| Parameter | Description |
|---|
timeoutSeconds | Maximum seconds to wait (max 60). If no card arrives, a Timeout status is returned. |
continuous | If true, polling restarts immediately after a timeout. A TransactionComplete event is sent with status PollContinuous. |
KIOSK_RET LibOtiKiosk_GetCardToken(otiKioskPaymentParameters *params);
PreAuthorize
This method initiates a pre-authorization transaction with a specified amount. It helps reserve funds without immediate settlement, for example, EV chargers reserve a maximum amount before actual usage. EMV Core will wait for a card to be presented to the reader, read it, and, if needed, process it with the payment service. It will then send the TransactionComplete event.
API Signature
Request:{"jsonrpc":"2.0","method":"PreAuthorize", "params": {"amount":450,
"timeout":10, "fee":0, "productID":0, "continuous":false}, "id":801}
{"jsonrpc": "2.0", "result": true, "id": 801}
| Parameter | Description |
|---|
| amount | Amount to charge – in full units (Dollars, not cents). |
| fee | Deprecated – Not used. |
| currency | Taken from configuration since SDK v1.4. |
| productID | Optional parameter: ID of the product selected by the consumer. This number will be saved in the server and available for reports. |
| continuous | If continuous is true, then poll for card will start immediately after card transaction timeout and TransactionComplete event will be sent with status ‘PollContinuous’. |
| timeout | Maximum seconds to wait. If no card arrives, the request returns a Timeout status. |
void PreAuthorize(int amountMinorUnits, int productID, int timeoutSeconds, boolean continuous) throws EmvCoreException;
| Parameter | Description |
|---|
amountMinorUnits | Amount to charge in minor units (e.g., cents, not dollars). |
productID | ID of the product selected by the consumer. This number will be saved on the server and available for reports. |
timeoutSeconds | Maximum wait time for card presentation. |
continuous | Whether to enable continuous polling. |
otiKioskPaymentParameters params = {
.amount_cents = 1500, // $15.00
.fee_cents = 0,
.product_id = 12345,
.timeout_sec = 60,
.continuous = false
};
KIOSK_RET result = LibOtiKiosk_PreAuthorize(¶ms);
if (result == KIOSK_RET_OK) {
printf("Payment initiated successfully\n");
}
| Parameter | Description |
|---|
amount_cents | Amount to charge in minor units (e.g., cents, not dollars). |
fee_cents | Optional fee amount in minor units. |
product_id | ID of the product selected by the consumer. This number will be saved on the server and available for reports. |
timeout_sec | Maximum wait time for card presentation. |
continuous | Whether to enable continuous polling. |
Setting productID to a non-zero value marks the pre-authorized amount as final; it cannot be changed in ConfirmTransaction. If the final amount is not yet known, set productID = 0 in PreAuthorize and provide the actual ID in ConfirmTransaction.
TransactionComplete event returns with status OK), the application must call the ConfirmTransaction or VoidTransaction methods to complete the workflow.
VoidTransaction
This request is used to void a transaction in two specific cases:
- Release Funds: The transaction was Pre-Authorized but not Confirmed. Voiding releases the reserved funds when the transaction will no longer occur.
- Reversal: The transaction was completed using
PayTransaction but needs to be canceled.
API Signature
Request: {"jsonrpc": "2.0", "method": "VoidTransaction", "params": {"transaction_Reference": "8453F02DFD33413EBA77334B696D5991"}, "id": 803}
{"jsonrpc": "2.0", "result": true, "id": 803}
| Parameter | Description |
|---|
| id | Command ID. |
| transactionReference | Transaction reference came from PSP with the TransactionComplete event. |
void VoidTransaction(String transactionReference) throws EmvCoreException;
| Parameter | Description |
|---|
transactionReference | Unique reference from pre-authorization. |
KIOSK_RET LibOtiKiosk_VoidTransaction(char* transaction_reference);
| Parameter | Description |
|---|
transaction_reference | Unique reference from pre-authorization. |
