Overview

2026-05-15 09:30

Note: Translation in progress.

Antom 线上和线下支付产品提供了一套用于与 Antom 集成的接口。您可以使用POST方法发送 HTTPS 请求并接收相应的响应。

以下部分介绍了报文结构和端到端的报文传输工作流程。

版本管理

当前接口版本为 v2。版本在地址中指定。例如，https://host/openapi/v2/payments/pay。

报文结构

在进行任何支付之前，了解 Antom 接口的工作原理以及请求和响应的结构非常重要。本节展示了您的系统与 Antom 之间交互数据的基本信息，例如报文结构和报文传输工作流程。报文指的是请求报文或响应报文。

请求结构

以下图示展示了请求报文的结构：

Request structure.png

图 1. 请求结构

HTTPS方法

POST

请求头

请求头主要包含以下字段。

头部字段	是否必需	描述	代码示例
Signature	是	包含由逗号(,)分隔的键值对。每个键值对是一个等式，由键和值用等号(=)连接。可以配置以下键：算法: 指定用于生成签名的数字签名算法。支持 RSA256，密钥长度必须为 2048 位。密钥版本: 指定用于生成或验证签名的密钥版本。默认为最新版本。签名: 包含请求的签名值。	`Signature: algorithm=RSA256, keyVersion=1, signature=****`
Encrypt	否	加密功能用密钥和算法来保证数据安全。算法：只支持 RSA_AES，表示用 RSA 和 AES 加密。密钥版本：加密用的密钥版本，默认为最新。对称密钥：用于加密、解密的密钥，可以是数字、字母或组合。	`algorithm=RSA_AES,keyVersion=1,symmetricKey=********`
Content-Type	是	表明 RFC2616 中定义的请求报文的媒体类型。其中，charset 用于生成/验证签名。	`Content-Type: application/json; charset=UTF-8`
Client-Id	是	用来识别客户端，与签名密钥相关联。注意：支付终端的序列号通常就是 Client-Id 的值。	`Client-Id: ****`
Request-Time	是	表示请求发送的时间，采用 ISO8601 格式。注意：时间必须精确到毫秒。	`Request-Time: 2019-04-04T12:08:56.253+05:30`
Accept	否	用于告知服务器客户端能处理哪些响应类型。用逗号分隔不同类型。注意：D-Store 的请求应设置为 `text/plain,text/xml,text/javascript,text/html,application/json`。	`Accept: text/plain,text/xml,text/javascript,text/html,application/json`

请求体

请求体包含 JSON 格式的详细请求信息。请求体中的字段根据服务的不同而变化。更多信息，请参阅特定接口规范的说明。

响应结构

以下图示展示了响应结构：

Response structure.png

图 2. 响应结构

响应头

响应头包含有关响应的信息，主要包含以下字段。

头部字段	是否必需	描述	代码示例
Signature	是	包含由逗号(,)分隔的键值对。每个键值对是一个等式，由键和值用等号(=)连接。可以配置以下键：算法: 指定用于生成签名的数字签名算法。支持 RSA256，密钥长度必须为 2048 位。密钥版本: 指定用于生成或验证签名的密钥版本。默认为最新版本。签名: 包含请求的签名值。	`Signature: algorithm=RSA256, keyVersion=1, signature=****`
Encrypt	否	加密功能用密钥和算法来保证数据安全。算法：只支持 RSA_AES，表示用 RSA 和 AES 加密。密钥版本：加密用的密钥版本，默认为最新。对称密钥：用于加密、解密的密钥，可以是数字、字母或组合。	`algorithm=RSA_AES,keyVersion=1,symmetricKey=********`
Content-Type	是	表明 RFC2616 中定义的请求报文的媒体类型。其中，charset 用于生成/验证签名。	`Content-Type: application/json; charset=UTF-8`
Client-Id	是	用来识别客户端，与签名密钥相关联。注意：支付终端的序列号通常就是 Client-Id 的值。	`Client-Id: ****`
Request-Time	是	表示请求发送的时间，采用 ISO8601 格式。注意：时间必须精确到毫秒。	`Request-Time: 2019-04-04T12:08:56.253+05:30`

响应体

响应体包含对客户端的响应信息。这一部分的字段根据服务的不同而变化。然而，总是包含 result 字段，它表示接口调用的结果。

当结果状态（ resultStatus ）为失败时，结果代码（ resultCode ）是一个错误代码，结果消息（ resultMessage ）是一个错误消息，用于故障排查。有关如何解决错误的更多信息，请参阅特定接口中的结果/错误码。

头部字段	类型	是否必需	描述
resultStatus	字符串	否	结果状态。有效值包括： `S` : 成功 `F` : 失败 `U` : 未知
resultCode	字符串（64 个字符）	否	结果代码。
resultMessage	字符串（256 个字符）	否	详细描述结果代码和状态的结果消息。

报文传输工作流程

整个交互序列如下所示：

Message transmission workflow.png

图 3. 消息传输工作流程

整体流程

遵循整体流程调用接口。

准备工作

为防止可能在响应中遇到的潜在错误，请考虑以下因素：

为防止可能在响应中遇到的错误，了解幂等性。
对包含特殊字符的请求进行编码。

1. 构建请求

构建一个遵循请求结构的请求。例如，在请求头中添加 client-Id ，request-time ， signature 等字段。

为了确保消息传输的安全，构建请求时请执行以下安全措施：

对请求报文进行签名。所有请求和响应都需要签名和签名验证。更多信息，请参阅请求签名及验证签名。
对请求进行编码，以防止请求中包含的特殊字符可能导致的错误或歧义。详情请参阅报文编码。

2. 发送请求

您可以通过您喜欢的平台或工具发送请求，例如，使用 Postman 或 cURL 命令。

3. 检查响应

响应通常以 JSON 或 XML 格式返回。有关响应的详细信息，请参阅响应结构部分。收到响应后，验证响应的签名。

4. 检查状态码

响应数据会根据服务的不同而变化，不过总是包含表示接口调用结果的 result 字段。如果发生错误，会返回一个错误响应，其中 result 对象会显示错误代码和错误消息，以便您排查问题。

幂等性

在支付过程中，POS 系统可能因网络超时或重复提交等原因，多次发送同一 paymentRequestId 的支付请求。Antom 通过幂等性键（idempotency key）确保同一支付请求仅被处理一次，有效防止重复扣款，保障用户资金安全。

处理规则：

支付已成功：若该 paymentRequestId 对应的支付已完成，则直接返回：

resultStatus = S（成功）
resultCode = SUCCESS

支付处理中：若该 paymentRequestId 对应的支付仍在异步处理中，则返回：

resultStatus = U（处理中）
resultCode = PAYMENT_IN_PROGRESS

支付失败：若该 paymentRequestId 对应的支付已确认失败，则返回：

resultStatus = F（失败）
resultCode = PAYMENT_FAIL

通过唯一的 paymentRequestId 标识每笔支付请求，并根据其最终状态返回明确响应，显著提升支付系统的可靠性与用户体验。