> ## Documentation Index
> Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Payment
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](#canceltransaction)
* [ConfirmTransaction](#confirmtransaction)
* [GetCardToken](#getcardtoken)
* [PreAuthorize](#preauthorize)
* [VoidTransaction](#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:
Request:
```json theme={null}
{"jsonrpc": "2.0", "method": "CancelTransaction", "id": 802}
```
Response:
```json theme={null}
{"jsonrpc": "2.0", "result": true, "id": 802}
```
```java Java theme={null}
void CancelTransaction();
```
```c C theme={null}
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 the authorization flow. It confirms the pre-authorization so that settlement can take place.
### API Signature
Response:
```json JSON theme={null}
{
"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
}
```
Request:
```json JSON theme={null}
{"jsonrpc":"2.0","method":"ConfirmTransaction", "params": {"amount":450, "fee":0, "productID":42, "transaction_Reference":"6103587330", "AdditionalReceiptData":{"Message": "Purchase confirmed", "VAT_Percentage": 10}}, "id":8}
```
Response:
```json JSON theme={null}
{"jsonrpc":"2.0", "result":true, "id":8}
```
**Parameters:**
| Parameter | Description |
| :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------- |
| **id** | Command ID. |
| **amount** | The actual amount to charge – in minor units (cents). |
| **transactionReference** | Transaction reference from the PSP. Use the `transactionId` 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)`. |
| **AdditionalReceiptData** | Optional. JSON object with extra receipt data to include at confirmation time. |
```java Java theme={null}
void ConfirmTransaction(String transactionReference, int actualAmountMinorUnits, int productID) throws EmvCoreException;
```
**Parameters:**
| Parameter | Description |
| ------------------------ | ---------------------------------------- |
| `transactionReference` | Unique reference from pre-authorization. |
| `actualAmountMinorUnits` | The final amount for settlement. |
| `productID` | Product identifier. |
```c C theme={null}
KIOSK_RET LibOtiKiosk_ConfirmTransaction(uint32_t amount_cents, uint32_t fee_cents, uint32_t product_id, char* transaction_reference, char* additional_receipt_data);
```
**Parameters:**
| Parameter | Description |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| `amount_cents` | Amount to charge in minor units (cents, not dollars). |
| `fee_cents` | Deprecated. Not used. |
| `transaction_reference` | Unique reference from pre-authorization. |
| `product_id` | Product identifier. |
| `additional_receipt_data` | Optional. JSON string with extra receipt data to include at confirmation time. Can be `NULL`. |
***
## `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 (for example, Mifare):** Returns the card UID.
### API Signature
Request:
```json theme={null}
{
"method": "GetCardToken",
"params": {
"continuous": false,
"timeout": 60
},
"id": 5820
}
```
Response:
```json JSON theme={null}
{"jsonrpc": "2.0", "result": true, "id": 5820}
```
**Parameters:**
| Parameter | Description |
| :----------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| **timeoutSeconds** | Maximum number of seconds to wait. If no card arrives within this time – return `Timeout` status. Maximum value is 60 seconds. |
```java Java theme={null}
void GetCardToken(int timeoutSeconds, boolean continuous) throws EmvCoreException;
```
**Parameters:**
| 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`. |
```c C theme={null}
KIOSK_RET LibOtiKiosk_GetCardToken(otiKioskPaymentParameters *params);
```
***
## `PreAuthorize`
Use `PreAuthorize` to pre-authorize a card with the payment processor. EMV Core waits for a card, reads it, and processes it with the payment service if needed. It then sends a `TransactionComplete` event.
### API Signature
Request:
```json JSON theme={null}
{"jsonrpc":"2.0","method":"PreAuthorize", "params": {"amount":450, "timeout":10, "productID":0, "continuous":false, "AdditionalReceiptData": {"Message": "Good Morning", "VAT_Percentage": 10}, "isFinalAmount":false, "deferred":false}, "id":801}
```
Response:
```json JSON theme={null}
{"jsonrpc": "2.0", "result": true, "id": 801}
```
**Parameters:**
| Parameter | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **amount** | Amount to charge in full units (Dollars, not cents). |
| **fee** | Deprecated. Not used. |
| **currency** | Taken from configuration since SDK v1.4. If `CURRENCY_CODE` is not set, SDK v1.5 reads the currency from the reader's tag `9F3C` on the first transaction, and falls back to USD (840) if that's also unavailable. |
| **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. |
| **AdditionalReceiptData** | Optional. JSON object with extra receipt data passed to the PSP and included in the eReceipt. |
| **isFinalAmount** | `true`: fixed amount, indicates `pre-selection` flow. `false`: amount may change, indicates `pre-authorization` flow. When used with `deferred=false`, the host must call `ConfirmTransaction` or `VoidTransaction` in both cases. When used with `deferred=true`, no need to call `ConfirmTransaction` or `VoidTransaction`. The transaction settles automatically. |
| **deferred** | Optional. `true`: Deferred Authorization (Transit mode). Card read offline, authorization queued for settlement. See Deferred Transaction for details. |
```java Java theme={null}
void PreAuthorize(int amountMinorUnits, int productID, int timeoutSeconds, boolean continuous) throws EmvCoreException;
```
**Parameters:**
| Parameter | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `amountMinorUnits` | Amount to charge in minor units (for example, 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. |
```c C theme={null}
otiKioskPaymentParameters params = {
.amount_cents = 1500, // $15.00
.product_id = 12345,
.timeout_sec = 60,
.continuous = false,
.additional_receipt_data = NULL,
.is_deferred = false,
.is_final_amount = false
};
KIOSK_RET result = LibOtiKiosk_PreAuthorize(¶ms);
if (result == KIOSK_RET_OK) {
printf("Payment initiated successfully\n");
}
```
**Parameters:**
| Parameter | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `amount_cents` | Amount to charge in minor units (for example, cents, not dollars). |
| `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. |
| `additional_receipt_data` | Optional. JSON string with extra receipt data passed to the PSP and included in the eReceipt. Can be `NULL`. |
| `is_deferred` | Optional. `true` for Deferred Authorization (Transit mode): the card is read offline and the authorization is queued for settlement. |
| `is_final_amount` | `true`: fixed amount, indicates the pre-selection flow. `false`: amount may change, indicates the pre-authorization flow. |
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`.
If the transaction is approved (the `TransactionComplete` event returns with status `OK`), your application must call `ConfirmTransaction` or `VoidTransaction` to complete the flow.
***
## `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
Request:
```json JSON theme={null}
{"jsonrpc": "2.0", "method": "VoidTransaction", "params": {"transaction_Reference": "8453F02DFD33413EBA77334B696D5991"}, "id": 803}
```
Response:
```json JSON theme={null}
{"jsonrpc": "2.0", "result": true, "id": 803}
```
**Parameters:**
| Parameter | Description |
| :----------------------- | :------------------------------------------------------------------------ |
| **id** | Command ID. |
| **transactionReference** | Transaction reference came from PSP with the `TransactionComplete` event. |
```java Java theme={null}
void VoidTransaction(String transactionReference) throws EmvCoreException;
```
**Parameters:**
| Parameter | Description |
| ---------------------- | ---------------------------------------- |
| `transactionReference` | Unique reference from pre-authorization. |
```c C theme={null}
KIOSK_RET LibOtiKiosk_VoidTransaction(char* transaction_reference);
```
**Parameters:**
| Parameter | Description |
| ----------------------- | ---------------------------------------- |
| `transaction_reference` | Unique reference from pre-authorization. |