支付 - Nayax Developer Portal

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

CancelTransaction
ConfirmTransaction
GetCardToken
IncrementalAuthorization
PreAuthorize
VoidTransaction

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

`CancelTransaction`

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

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

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

JSON
Android
Linux

请求：

 {"jsonrpc": "2.0", "method": "CancelTransaction", "id": 802}

响应：

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

Java

void CancelTransaction();

KIOSK_RET LibOtiKiosk_CancelTransaction(void);

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

`ConfirmTransaction`

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

API 签名

JSON
Android
Linux

响应：

JSON

{
  "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

{"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

    {"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 对象。

Java

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

参数：

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

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

`GetCardToken`

GetCardToken 方法用于启动卡片令牌化流程，返回卡片令牌而不执行金融交易。 EMV Core 等待卡片被轻触，读取数据，并触发 CardTokenReceived 事件：

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

API 签名

JSON
Android
Linux

请求：

{
"method": "GetCardToken",
"params": {
"continuous": false,
"timeout": 60
},
"id": 5820
}

响应：

JSON

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

参数：

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

Java

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

参数：

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

KIOSK_RET LibOtiKiosk_GetCardToken(otiKioskPaymentParameters *params);

`IncrementalAuthorization`

IncrementalAuthorization 方法为现有已授权交易添加增量扣款，并通过 IncrementalAuthorizationResponse 回调返回结果。该方法是为未来的多步流程保留的，目前无需使用：如需了解当前的单步行为，请参阅下文。

单步增量授权

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

调用 PreAuthorize（例如 10.00 美元），并从返回的 TransactionComplete 事件中读取 IncrementalMaxDefaultCredit 的值（例如 50.00 美元）。
调用 ConfirmTransaction，或从您的服务器发送外部结算请求，金额不超过 IncrementalMaxDefaultCredit（例如 15.03 美元）。
Nayax Core 会自动向处理商发送针对差额的增量授权请求（本例中为 5.03 美元）。
如果增量授权成功，Nayax Core 会以最终金额（15.03 美元）结算交易。
如果失败，Nayax Core 会以原始预授权金额（10.00 美元）结算交易。

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

此方法仅适用于 Android SDK。

请参阅下方 IncrementalAuthorization 的 API 签名：

Java

void IncrementalAuthorization(int amountMinorUnits, int productID, String transactionReference) throws EmvCoreException;

参数：

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

`PreAuthorize`

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

API 签名

JSON
Android
Linux

请求：

JSON

{"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

   {"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 模式）。卡片离线读取，授权排队等待结算。详情请参阅延迟交易。

Java

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 模式）。卡片离线读取，授权排队等待结算。详情请参阅延迟交易。
`isFinalAmount`	`true`：固定金额，表示 `pre-selection`（预选）流程。`false`：金额可能变化，表示 `pre-authorization`（预授权）流程。当与 `isDeferred=false` 一起使用时，主机在两种情况下都必须调用 `ConfirmTransaction` 或 `VoidTransaction`。当与 `isDeferred=true` 一起使用时，无需调用 `ConfirmTransaction` 或 `VoidTransaction`，交易将自动结算。在 SDK v1.5 中，`isDeferred=true` 仅在 `isFinalAmount=true` 时受支持。

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` 时受支持。

在 SDK v1.5 之前： 在 PreAuthorize 中将 productID 设置为非零值，会将预授权金额标记为最终金额，且无法在 ConfirmTransaction 中更改。若要表示金额尚未确定，则在 PreAuthorize 中设置 productID = 0，并在 ConfirmTransaction 中提供实际的产品 ID。自 SDK v1.5 起，金额是否为最终金额改由 PreAuthorize 中的 isFinalAmount 参数控制（详见上方参数表）。productID 现在仅用于报告，可在两次调用中独立设置。

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

`VoidTransaction`

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

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

API 签名

JSON
Android
Linux

请求：

JSON

 {"jsonrpc": "2.0", "method": "VoidTransaction", "params": {"transaction_Reference": "8453F02DFD33413EBA77334B696D5991"}, "id": 803}

响应：

JSON

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

参数：

参数	描述
id	命令 ID。
transactionReference	来自 PSP 的交易引用，随 `TransactionComplete` 事件返回。

Java

void VoidTransaction(String transactionReference) throws EmvCoreException;

参数：

参数	描述
`transactionReference`	来自预授权的唯一引用。

KIOSK_RET LibOtiKiosk_VoidTransaction(char* transaction_reference);

参数：

参数	描述
`transaction_reference`	来自预授权的唯一引用。

EMV Core Guides

Android & Linux SDK

RTOS SDK

UNO-mini Hardware

Release Notes

支付

`CancelTransaction`

`ConfirmTransaction`

API 签名

`GetCardToken`

API 签名

`IncrementalAuthorization`

单步增量授权

`PreAuthorize`

API 签名

`VoidTransaction`

API 签名

​CancelTransaction

​ConfirmTransaction

​API 签名

​GetCardToken

​API 签名

​IncrementalAuthorization

​单步增量授权

​PreAuthorize

​API 签名

​VoidTransaction

​API 签名

`CancelTransaction`

`ConfirmTransaction`

API 签名

`GetCardToken`

API 签名

`IncrementalAuthorization`

单步增量授权

`PreAuthorize`

API 签名

`VoidTransaction`

API 签名