C API 参考

概述

EMV Core 为 POS 应用程序提供两个 API 层：

C 函数，在 libecodsdk 中实现。请参阅 SDK 中的 ecod_sdk.h 和 ecod_sdk_types.h。
JSON-RPC 消息，通过串口或 USB 使用 Datalink 封装传输。请参阅 JSON-RPC API。

POS 应用程序管理用户界面，使用 EMV Core 的读卡器状态事件来保持显示与当前支付状态（空闲、正在授权、已拒绝、已批准等）同步。

支持的功能

该 SDK 支持以下支付和设备管理操作：

信用卡 / 借记卡 / 预付卡销售：
- EMV 非接触式（仅限无 CVM）
- 两步交易（授权→确认）
- 闭环（预付费）卡
- 同步（单会话）和异步（多会话）流程
取消和撤销交易：
- CancelTransaction 会在读取到卡片之前取消正在进行的轮询。
- VoidTransaction 会撤销已批准的交易。
用户界面（UI）： 由 POS 应用程序使用读卡器状态事件进行管理。
终端管理： 固件和配置更新、状态和版本查询、设备 ID。
网络 API： 主机必须实现网络 API 才能启用 EMV Core 与 Nayax 服务器的通信。

API 参考

初始化和生命周期

获取 SDK 版本字符串

返回 SDK 版本，以空字符结尾的字符串形式表示：

const char* EcodSdk_GetSdkVersion(void);

初始化 SDK

启动时调用一次：

bool EcodSdk_Init(void);

维护循环

从专用线程持续调用：

void EcodSdk_Maintain(void);

处理 JSON-RPC 消息

当 EC_USE_DATALINK_PROTOCOL=1 时，从第二个线程调用：

int EcodSdk_ProcessMessages(uint32_t timeout_ms);

启用 EC_USE_DATALINK_PROTOCOL 后，需要第二个线程来处理 JSON-RPC 消息。调用 EcodSdk_Maintain() 处理数据链路操作，调用 EcodSdk_ProcessMessages() 处理消息。

设置日志详细程度

调用此函数控制 SDK 日志输出的详细程度：

EC_RET EcodSdk_SetLogLevel(EC_LOG_LEVEL max_level);

设备状态

获取当前设备状态

调用以查询当前设备状态：

EC_RET EcodSdk_GetStatus(EC_STATUS* out_status);

获取设备标识（序列号）和版本

调用此函数以获取设备序列号和固件版本字符串：

EC_RET EcodSdk_GetKioskId(char* out_id, int max_out_size);
EC_RET EcodSdk_GetEmvCoreVersion(char* out_version, int max_out_size);
EC_RET EcodSdk_GetReaderVersion(char* out_version, int max_out_size);

读取配置属性

返回当前配置文件中指定键的值：

EC_RET EcodSdk_GetAttribute(char* attribute_name, char* out_value, int max_out_size);

交易操作

开始预授权

预留相应金额；稍后需确认或作废：

EC_RET EcodSdk_PreAuthorize(emvCorePaymentParameters* params);

获取卡令牌（不扣款）

启动读卡轮询，但不发起支付：

EC_RET EcodSdk_GetCardToken(emvCorePaymentParameters* params);

确认预授权交易

产品或服务交付后调用：

EC_RET EcodSdk_ConfirmTransaction(uint32_t amount_cents, uint32_t product_id,
                                   char* transaction_reference);

撤销预授权交易

调用以解除预授权冻结，不向卡片扣款：

EC_RET EcodSdk_VoidTransaction(char* transaction_reference);

取消正在进行的支付流程

调用以在授权完成之前停止正在进行的读卡轮询：

EC_RET EcodSdk_CancelTransaction(void);

网络通知

这些函数由平台层调用，用于通知 SDK 网络事件：

通知 EmvCore 套接字数据已到达

当套接字上存在数据时，从平台层调用：

EC_RET EcodSdk_NotifySocketDataReceived(int socket_id, int available_bytes);

通知 EmvCore 套接字已关闭

当套接字连接关闭时，从平台层调用：

EC_RET EcodSdk_NotifySocketClosed(int socket_id);

通知 EmvCore 网络连接变更

当网络可用或不可用时，从平台层调用：

EC_RET EcodSdk_NotifyNetworkStatusChanged(bool available);

回调注册

交易完成（成功、拒绝、错误、取消、超时）

注册一个处理程序以接收每次 PreAuthorize 调用的结果：

void EcodSdk_Register_TransactionComplete_Callback(TransactionCompleteCb_t cb);

读卡器显示事件（客户提示）

注册处理程序，接收读卡器上当前显示的消息：

void EcodSdk_Register_ReaderEvent_Callback(RdrEventCb_t cb);

关键数据类型

支付参数

将此结构体传递给 EcodSdk_PreAuthorize 和 EcodSdk_GetCardToken：

typedef struct {
    uint32_t amount_cents;           // Amount in cents (1500 = $15.00)
    uint32_t product_id;             // Product identifier
    unsigned int timeout_sec;        // Timeout for card presentation
    bool continuous;                 // Wait continuously until cancelled
    char* additional_receipt_data;   // Optional JSON string (can be NULL)
    bool is_deferred;                // Deferred authorization (charge later) — RFU
    bool is_final_amount;            // Amount won't change (no incremental auth)
} emvCorePaymentParameters;

交易响应

此结构体会传递给 TransactionComplete 回调：

typedef struct {
    emvCoreTransStatus status;          // OK, Declined, Error, Timeout, Cancelled, etc.
    int error_code;                     // Error code if status is Error
    char error_message[100];            // Human-readable error
    double amount_requested;            // Amount that was requested
    double amount_authorized;           // Amount actually authorized
    char transaction_reference[128];    // Use for confirm/void/incremental
    char partial_PAN[20];               // Masked card number (****1234)
    char card_type[32];                 // VISA, MASTERCARD, etc.
    char card_id[64];                   // Unique card identifier
    char card_token[128];               // Tokenized card data
    char authorization_code[128];       // Auth code from processor
    char rrn[128];                      // Retrieval reference number
    bool is_transaction_approved;       // True if approved
    // ... additional fields for receipt, balance, Nayax info
} emvCorePaymentResponse;

状态码

设备状态（来自 EcodSdk_GetStatus）：

typedef enum {
    EC_READY,           // Ready for transactions
    EC_TRANSACTION,     // Transaction in progress
    EC_UNCONFIRMED,     // Pending transaction needs confirm/void
    EC_UPDATE,          // Device updating
    EC_NOT_READY,       // Initializing
    EC_NO_EMVCORE,      // Cannot communicate with device
    EC_NO_READER,       // Reader not connected
    EC_NO_TERMINAL_ID,  // Terminal ID not configured
    EC_DISABLED,        // Device disabled
    EC_ERROR            // Error state
} EC_STATUS;

API 返回码：

typedef enum {
    EC_RET_OK,              // Success
    EC_RET_GENERAL_ERROR,   // General error
    EC_RET_MEMORY_ERROR,    // Memory allocation failed
    EC_RET_PARSING_ERROR,   // Response parsing failed
    EC_RET_COMM_ERROR,      // Communication error
    EC_RET_NEGATIVE_RESP    // Device returned error
} EC_RET;

交易状态：

typedef enum {
    emvCoreTransStatus_OK,           // Success
    emvCoreTransStatus_Declined,     // Declined by processor
    emvCoreTransStatus_Error,        // Error occurred
    emvCoreTransStatus_Timeout,      // Card presentation timeout
    emvCoreTransStatus_Cancelled,    // Cancelled by application
    emvCoreTransStatus_Voided,       // Transaction voided
    emvCoreTransStatus_LocalCLP      // Local closed-loop payment
} emvCoreTransStatus;

金额字段详情

金额字段根据 API 方法的不同使用不同的单位：

C API： emvCorePaymentParameters 中的 amount_cents 以及 EcodSdk_ConfirmTransaction 的金额参数始终以美分为单位（例如 450 = 4.50 美元）。
JSON-RPC PreAuthorize： 金额以美分为单位（例如 450 = 4.50 美元）。
JSON-RPC ConfirmTransaction： 金额以美分为单位（例如 450 = 4.50 美元）。
TransactionComplete 事件中的 amount 字段按 PSP 返回的主要货币单位表示（例如 4.50 美元）。
fee 参数已弃用，请将其设为 0。它将在下一版 SDK 中移除。

货币代码管理

SDK 按以下优先级顺序从多个来源解析货币代码：

自 SDK v1.0 起，货币代码取自 EMV Core 配置中的 CURRENCY_CODE 属性。
如果配置中缺少 CURRENCY_CODE，则使用主机在 PreAuthorize 中发送的 currency 参数（向后兼容）。
如果两者都未提供，则使用 EMV Core 软件默认值（840 / USD），并向 Nayax Core 服务器发送警报。
当设备由 Nayax Core 管理时，货币代码会自动从机器设置中获取。

EMV Core Guides

Android & Linux SDK

RTOS SDK

UNO-mini Hardware

Release Notes

概述

支持的功能

API 参考

初始化和生命周期

获取 SDK 版本字符串

初始化 SDK

维护循环

处理 JSON-RPC 消息

设置日志详细程度

设备状态

获取当前设备状态

获取设备标识（序列号）和版本

读取配置属性

交易操作

开始预授权

获取卡令牌（不扣款）

确认预授权交易

撤销预授权交易

取消正在进行的支付流程

网络通知

通知 EmvCore 套接字数据已到达

通知 EmvCore 套接字已关闭

通知 EmvCore 网络连接变更

回调注册

交易完成（成功、拒绝、错误、取消、超时）

读卡器显示事件（客户提示）

关键数据类型

支付参数

交易响应

状态码

金额字段详情

货币代码管理

​概述

​支持的功能

​API 参考

​初始化和生命周期

​获取 SDK 版本字符串

​初始化 SDK

​维护循环

​处理 JSON-RPC 消息

​设置日志详细程度

​设备状态

​获取当前设备状态

​获取设备标识（序列号）和版本

​读取配置属性

​交易操作

​开始预授权

​获取卡令牌（不扣款）

​确认预授权交易

​撤销预授权交易

​取消正在进行的支付流程

​网络通知

​通知 EmvCore 套接字数据已到达

​通知 EmvCore 套接字已关闭

​通知 EmvCore 网络连接变更

​回调注册

​交易完成（成功、拒绝、错误、取消、超时）

​读卡器显示事件（客户提示）

​关键数据类型

​支付参数

​交易响应

​状态码

​金额字段详情

​货币代码管理

概述

支持的功能

API 参考

初始化和生命周期

获取 SDK 版本字符串

初始化 SDK

维护循环

处理 JSON-RPC 消息

设置日志详细程度

设备状态

获取当前设备状态

获取设备标识（序列号）和版本

读取配置属性

交易操作

开始预授权

获取卡令牌（不扣款）

确认预授权交易

撤销预授权交易

取消正在进行的支付流程

网络通知

通知 EmvCore 套接字数据已到达

通知 EmvCore 套接字已关闭

通知 EmvCore 网络连接变更

回调注册

交易完成（成功、拒绝、错误、取消、超时）

读卡器显示事件（客户提示）

关键数据类型

支付参数

交易响应

状态码

金额字段详情

货币代码管理