Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

概述

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 标识每笔支付请求，并根据其最终状态返回明确响应，显著提升支付系统的可靠性与用户体验。