> ## 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.

# 支付

EMV Core SDK 提供用于管理支付交易的 API。通过这些 API，您可以将无现金支付功能集成到应用程序中，同时支持开环和闭环系统。该 SDK 负责安全、高效且灵活的支付处理，并将复杂逻辑转移至 Nayax 后端。

可用于支付管理的方法有：

* [CancelTransaction](#canceltransaction)
* [ConfirmTransaction](#confirmtransaction)
* [GetCardToken](#getcardtoken)
* [IncrementalAuthorization](#incrementalauthorization)
* [PreAuthorize](#preauthorize)
* [VoidTransaction](#voidtransaction)

以下部分对它们进行了更详细的描述。

***

## `CancelTransaction`

`CancelTransaction` 方法会停止正在进行的 `PayTransaction` 或 `PreAuthorize` 调用的执行。在取消操作被接受并确认之前，系统会阻止进一步的请求。

**实现说明：**

* **轻触卡片之前：** 如果尚未轻触卡片，读卡器轮询序列将停止。显示屏将显示 **“Cancelling”**（取消中）；随后主机应用程序必须使用 `ShowMessage` 命令更新界面。
* **处理过程中：** 如果卡片已经被轻触但处理尚未完成，系统会返回 `CannotCancel`。EMV Core 在等待联机结果时，可能需要几秒钟才能收到 `TransactionComplete` 事件。
* **完成之后：** 如果交易已经完成，将返回 `NoTransaction`。
* **撤销已成功交易：** 要撤销已完成的交易，请使用 `VoidTransaction`。
* **被拒绝的交易：** 如果 `TransactionComplete` 返回 `Decline` 状态，则无需发送 `VoidTransaction` 命令。
* **事件：** 在所有情况下，EMV Core 最终都会发送 `TransactionComplete` 事件以确定最终状态。

请参阅下方 `CancelTransaction` 方法的 API 签名：

<Tabs>
  <Tab title="JSON">
    请求：

    ```json theme={null}
     {"jsonrpc": "2.0", "method": "CancelTransaction", "id": 802}
    ```

    响应：

    ```json theme={null}
      {"jsonrpc": "2.0", "result": true, "id": 802}
    ```
  </Tab>

  <Tab title="Android">
    ```java Java theme={null}
    void CancelTransaction();
    ```
  </Tab>

  <Tab title="Linux">
    ```c C theme={null}
    KIOSK_RET LibOtiKiosk_CancelTransaction(void);
    ```
  </Tab>
</Tabs>

<Note>
  如果卡片已被轻触并处理完毕，系统将返回 `CannotCancel` 错误。
</Note>

***

## `ConfirmTransaction`

确认请求是授权流程的第二阶段，用于确认预授权，以便进行结算。

### API 签名

<Tabs>
  <Tab title="JSON">
    响应：

    ```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
    }
    ```

    请求：

    ```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}
    ```

    响应：

    ```json JSON theme={null}
        {"jsonrpc":"2.0", "result":true, "id":8}
    ```

    参数：

    | 参数 | 描述 |
    | :- | :- |
    | **id** | 命令 ID。 |
    | **amount** | 实际收费金额，以最小货币单位（分）表示。 |
    | **transactionReference** | 来自 PSP 的交易引用。使用 `TransactionComplete` 事件中的 `transactionId` 字段。 |
    | **productID** | 可选参数：消费者所选产品的ID。该编号将保存在服务器上，并可用于生成报告。在 SDK v1.5 之前，`productID` 还用于控制预授权金额是否为最终金额；该行为现由 `PreAuthorize` 中的 `isFinalAmount` 控制。 |
    | **terminal\_data** | 可选参数：`terminal_data=(key1=value1,key2=value2)`。 |
    | **AdditionalReceiptData** | 可选。包含确认时要附加的额外收据数据的 JSON 对象。 |
  </Tab>

  <Tab title="Android">
    ```java Java theme={null}
    void ConfirmTransaction(String transactionReference, int actualAmountMinorUnits, int productID) throws EmvCoreException;
    ```

    参数：

    | 参数 | 描述 |
    | - | - |
    | `transactionReference` | 来自预授权的唯一引用。 |
    | `actualAmountMinorUnits` | 最终结算金额。 |
    | `productID` | 产品标识符。 |
  </Tab>

  <Tab title="Linux">
    ```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);
    ```

    参数：

    | 参数 | 描述 |
    | - | - |
    | `amount_cents` | 以最小货币单位（美分，而非美元）计的收费金额。 |
    | `fee_cents` | 已弃用。未使用。 |
    | `transaction_reference` | 来自预授权的唯一引用。 |
    | `product_id` | 产品标识符。 |
    | `additional_receipt_data` | 可选。包含确认时要附加的额外收据数据的 JSON 字符串。可以为 `NULL`。 |
  </Tab>
</Tabs>

***

## `GetCardToken`

`GetCardToken` 方法用于启动卡片令牌化流程，返回卡片令牌而不执行金融交易。

EMV Core 等待卡片被轻触，读取数据，并触发 `CardTokenReceived` 事件：

* **支付卡：** 返回包含卡令牌的 Base64 字符串。
* **CLP 卡（例如 Mifare）：** 返回卡片 UID。

### API 签名

<Tabs>
  <Tab title="JSON">
    请求：

    ```json theme={null}
    {
    "method": "GetCardToken",
    "params": {
    "continuous": false,
    "timeout": 60
    },
    "id": 5820
    }

    ```

    响应：

    ```json JSON theme={null}
       {"jsonrpc": "2.0", "result": true, "id": 5820}
    ```

    参数：

    | 参数 | 描述 |
    | :- | :- |
    | **timeoutSeconds** | 等待的最长秒数。如果在此时间内没有卡片到达，则返回 `Timeout` 状态。最大值为 60 秒。 |
  </Tab>

  <Tab title="Android">
    ```java Java theme={null}
    void GetCardToken(int timeoutSeconds, boolean continuous) throws EmvCoreException;
    ```

    参数：

    | 参数 | 描述 |
    | - | - |
    | `timeoutSeconds` | 最长等待秒数（最大 60 秒）。如果没有卡片到达，将返回 `Timeout` 状态。 |
    | `continuous` | 如果为 true，则在超时后立即重新开始轮询，并发送状态为 `PollContinuous` 的 `TransactionComplete` 事件。 |
  </Tab>

  <Tab title="Linux">
    ```c C theme={null}
    KIOSK_RET LibOtiKiosk_GetCardToken(otiKioskPaymentParameters *params);
    ```
  </Tab>
</Tabs>

***

## `IncrementalAuthorization`

`IncrementalAuthorization` 方法为现有已授权交易添加增量扣款，并通过 [`IncrementalAuthorizationResponse`](/docs/zh/integrate-pos-device/emv-core/sdk-methods-functions/event-callbacks#incrementalauthorizationresponse) 回调返回结果。该方法是为未来的多步流程保留的，目前无需使用：如需了解当前的单步行为，请参阅下文。

### 单步增量授权

在大多数场景下，您无需直接调用此 API。每当结算金额超过预授权金额时，Nayax Core 会自动处理单步增量授权：

1. 调用 `PreAuthorize`（例如 10.00 美元），并从返回的 `TransactionComplete` 事件中读取 `IncrementalMaxDefaultCredit` 的值（例如 50.00 美元）。
2. 调用 `ConfirmTransaction`，或从您的服务器发送[外部结算](/docs/zh/integrate-pos-device/emv-core/payment-flows/pre-authorization-with-external-settlement)请求，金额不超过 `IncrementalMaxDefaultCredit`（例如 15.03 美元）。
3. Nayax Core 会自动向处理商发送针对差额的增量授权请求（本例中为 5.03 美元）。
4. 如果增量授权成功，Nayax Core 会以最终金额（15.03 美元）结算交易。
5. 如果失败，Nayax Core 会以原始预授权金额（10.00 美元）结算交易。

<Note>
  Nayax 目前尚未在服务器端支持多步流程。目前调用 `IncrementalAuthorization` 除上述内容外不会产生其他效果。
</Note>

<Warning>
  此方法仅适用于 Android SDK。
</Warning>

请参阅下方 `IncrementalAuthorization` 的 API 签名：

```java Java theme={null}
void IncrementalAuthorization(int amountMinorUnits, int productID, String transactionReference) throws EmvCoreException;
```

参数：

| 参数 | 描述 |
| - | - |
| `amountMinorUnits` | 追加扣款金额，以最小货币单位（分）表示。 |
| `productID` | 可选。用于报告的产品 ID。 |
| `transactionReference` | 来自 `TransactionComplete` 的交易引用（`TransactionID` 字段）。 |

***

## `PreAuthorize`

使用 `PreAuthorize` 对支付处理商的卡片进行预授权。EMV Core 会等待卡片、读取卡片，并在需要时通过支付服务进行处理，然后发送 `TransactionComplete` 事件。

### API 签名

<Tabs>
  <Tab title="JSON">
    请求：

    ```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}
    ```

    响应：

    ```json JSON theme={null}
       {"jsonrpc": "2.0", "result": true, "id": 801}

    ```

    参数：

    | 参数 | 描述 |
    | :- | :- |
    | **amount** | 以最小货币单位（美分，而非美元）表示的扣款金额。例如，450 表示 4.50 美元。 |
    | **fee** | 已弃用。未使用。 |
    | **currency** | 自 SDK v1.4 起从配置中获取。如果未设置 `CURRENCY_CODE`，SDK v1.5 会在首次交易时从读卡器的标签 `9F3C` 中读取货币；如果该标签也不可用，则回退为美元（840）。 |
    | **productID** | 可选参数：消费者所选产品的ID。该编号将保存在服务器上，并可用于生成报告。 |
    | **continuous** | 如果 `continuous` 为 true，则读卡轮询将在交易超时后立即重新开始，并发送状态为 `PollContinuous` 的 `TransactionComplete` 事件。 |
    | **timeout** | 等待的最长秒数。如果没有卡片到达，请求将返回 `Timeout` 状态。 |
    | **AdditionalReceiptData** | 可选。包含传递给 PSP 并包含在 eReceipt 中的额外收据数据的 JSON 对象。 |
    | **isFinalAmount** | `true`：固定金额，表示 `pre-selection`（预选）流程。`false`：金额可能变化，表示 `pre-authorization`（预授权）流程。当与 `deferred=false` 一起使用时，主机在两种情况下都必须调用 `ConfirmTransaction` 或 `VoidTransaction`。当与 `deferred=true` 一起使用时，无需调用 `ConfirmTransaction` 或 `VoidTransaction`，交易将自动结算。在 SDK v1.5 中，`deferred=true` 仅在 `isFinalAmount=true` 时受支持。 |
    | **deferred** | 可选。`true`：延迟授权（Transit 模式）。卡片离线读取，授权排队等待结算。详情请参阅[延迟交易](/docs/zh/integrate-pos-device/emv-core/payment-flows/deferred-transaction)。 |
  </Tab>

  <Tab title="Android">
    ```java Java theme={null}
    void PreAuthorize(int amountMinorUnits, int productID, int timeoutSeconds, boolean continuous, JSONObject additionalReceiptData, boolean isDeferred, boolean isFinalAmount) throws EmvCoreException;
    ```

    参数：

    | 参数 | 描述 |
    | - | - |
    | `amountMinorUnits` | 以最小货币单位计的扣款金额（例如，以分而非元为单位）。 |
    | `productID` | 消费者所选产品的ID。该编号将保存在服务器上，并可用于生成报告。 |
    | `timeoutSeconds` | 轻触卡片的最长等待时间。 |
    | `continuous` | 是否启用持续轮询。 |
    | `additionalReceiptData` | 可选。包含传递给 PSP 并包含在 eReceipt 中的额外收据数据的 JSON 对象。如不使用，请传入 null。 |
    | `isDeferred` | 可选。`true`：延迟授权（Transit 模式）。卡片离线读取，授权排队等待结算。详情请参阅[延迟交易](/docs/zh/integrate-pos-device/emv-core/payment-flows/deferred-transaction)。 |
    | `isFinalAmount` | `true`：固定金额，表示 `pre-selection`（预选）流程。`false`：金额可能变化，表示 `pre-authorization`（预授权）流程。当与 `isDeferred=false` 一起使用时，主机在两种情况下都必须调用 `ConfirmTransaction` 或 `VoidTransaction`。当与 `isDeferred=true` 一起使用时，无需调用 `ConfirmTransaction` 或 `VoidTransaction`，交易将自动结算。在 SDK v1.5 中，`isDeferred=true` 仅在 `isFinalAmount=true` 时受支持。 |
  </Tab>

  <Tab title="Linux">
    ```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(&params);
    if (result == KIOSK_RET_OK) {
        printf("Payment initiated successfully\n");
    }
    ```

    参数：

    | 参数 | 描述 |
    | - | - |
    | `amount_cents` | 以最小货币单位计的扣款金额（例如，以分而非元为单位）。 |
    | `product_id` | 消费者所选产品的ID。该编号将保存在服务器上，并可用于生成报告。 |
    | `timeout_sec` | 轻触卡片的最长等待时间。 |
    | `continuous` | 是否启用持续轮询。 |
    | `additional_receipt_data` | 可选。包含传递给 PSP 并包含在 eReceipt 中的额外收据数据的 JSON 字符串。可以为 `NULL`。 |
    | `is_deferred` | 可选。`true` 表示延迟授权（Transit 模式）：卡片离线读取，授权排队等待结算。 |
    | `is_final_amount` | `true`：固定金额，表示预选流程。`false`：金额可能变化，表示预授权流程。在 SDK v1.5 中，`is_deferred=true` 仅在 `is_final_amount=true` 时受支持。 |
  </Tab>
</Tabs>

<Warning>
  **在 SDK v1.5 之前：** 在 `PreAuthorize` 中将 `productID` 设置为非零值，会将预授权金额标记为最终金额，且无法在 `ConfirmTransaction` 中更改。若要表示金额尚未确定，则在 `PreAuthorize` 中设置 `productID = 0`，并在 `ConfirmTransaction` 中提供实际的产品 ID。

  **自 SDK v1.5 起**，金额是否为最终金额改由 `PreAuthorize` 中的 `isFinalAmount` 参数控制（详见上方参数表）。`productID` 现在仅用于报告，可在两次调用中独立设置。
</Warning>

如果交易获批准（`TransactionComplete` 事件返回状态为 `OK`），应用程序必须调用 `ConfirmTransaction` 或 `VoidTransaction` 以完成流程。

***

## `VoidTransaction`

此请求用于在两种特定情况下撤销交易：

1. **释放资金：** 该交易已被**预授权**但尚未**确认**。撤销交易会在交易不会再发生时释放已预留的资金。
2. **冲正：** 交易已使用 `PayTransaction` 完成，但需要取消。

### API 签名

<Tabs>
  <Tab title="JSON">
    请求：

    ```json JSON theme={null}
     {"jsonrpc": "2.0", "method": "VoidTransaction", "params": {"transaction_Reference": "8453F02DFD33413EBA77334B696D5991"}, "id": 803}
    ```

    响应：

    ```json JSON theme={null}
     {"jsonrpc": "2.0", "result": true, "id": 803}
    ```

    参数：

    | 参数 | 描述 |
    | :- | :- |
    | **id** | 命令 ID。 |
    | **transactionReference** | 来自 PSP 的交易引用，随 `TransactionComplete` 事件返回。 |
  </Tab>

  <Tab title="Android">
    ```java Java theme={null}
    void VoidTransaction(String transactionReference) throws EmvCoreException;
    ```

    参数：

    | 参数 | 描述 |
    | - | - |
    | `transactionReference` | 来自预授权的唯一引用。 |
  </Tab>

  <Tab title="Linux">
    ```c C theme={null}
    KIOSK_RET LibOtiKiosk_VoidTransaction(char* transaction_reference);
    ```

    参数：

    | 参数 | 描述 |
    | - | - |
    | `transaction_reference` | 来自预授权的唯一引用。 |
  </Tab>
</Tabs>

<br />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.