EMV Core SDK Payment Management

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:

• CancelTransaction
• ConfirmTransaction
• GetCardToken
• PreAuthorize
• VoidTransaction

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:

void CancelTransaction();

🚧

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

void ConfirmTransaction(String transactionReference, int actualAmountMinorUnits, int productID) throws EmvCoreException;

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

void GetCardToken(int timeoutSeconds, boolean continuous) throws EmvCoreException;

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

void PreAuthorize(int amountMinorUnits, int productID, int timeoutSeconds, boolean continuous) throws EmvCoreException;

🚧

Setting productID ≠ 0 indicates that the amount set in PreAuthorize is final and will not change in ConfirmTransaction. If the final amount is unknown at this stage, use productID = 0 in PreAuthorize and set the actual product ID during ConfirmTransaction.

If the transaction is approved (the 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:

1. Release Funds: The transaction was Pre-Authorized but not Confirmed. Voiding releases the reserved funds when the transaction will no longer occur.
2. Reversal: The transaction was completed using PayTransaction but needs to be canceled.

API Signature

void VoidTransaction(String transactionReference) throws EmvCoreException;