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

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

版本管理

当前接口版本为v1。版本在地址中指定。例如，https://{domain name}/ams/api/v1/payments/pay。

环境

您可以根据所在地区选择下方列出的域名之一。建议使用加速域名，以便更快地接入 Antom。如果在设置加速域名时遇到问题，请联系 Antom 技术支持。

表1. 位置域名

报文结构

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

请求结构

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

图1. 请求结构  

地址

请求地址为 https://{domain name}/ams/api/{version}/{endpoint} ，其结构如下：

• 域名: 是由支付方式后端分配的标准域名。
• 版本: 是接口的版本号，例如，v1或v2。
• 端点: 是接口的访问地址，例如，/{version}/payments/pay。

一个接口可以通过其端点唯一标识。例如，/v1/payments/pay与/v2/payments/pay是不同的。

HTTPS方法

POST

请求头

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

注意：字段名称不区分大小写。

表2. 请求头

每个头字段的详细信息，请参阅以下描述。

signature Required

signature 包含由逗号(,)分隔的键值对。每个键值对是一个等式，由键和值用等号(=)连接。有关生成签名的详细信息，请参阅生成签名部分。

可以配置以下键：

• 算法 : 指定用于生成签名的数字签名算法。 支持 RSA256。
• 密钥版本: 指定用于生成或验证签名的密钥版本。默认情况下，该值为与 Client-Id 关联的最新密钥版本。
• 签名 : 包含请求的签名值。

示例：

Signature: algorithm=RSA256, keyVersion=1,
signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR
rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT
pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr
bRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%
2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3D

Content-Type Optional

Content-Type 表明 RFC2616 中定义的请求报文的媒体类型。其中，charset 用于生成/验证签名。

例如：

Content-Type: application/json; charset=UTF-8

client-id Required

client-id 用于标识客户端，并与用于签名的密钥相关联。有关获取客户端 ID 的详细信息，请参阅 Antom Dashboard。

request-time Required

request-time 指定请求发送时的时间戳。此字段的值必须精确到毫秒。使用编程语言中的方法获取时间戳：

• Java: System.currentTimeMillis()
• Python: round(time.time() * 1000)
• .Net: DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
• PHP: round(microtime(true) * 1000)

request-time: 1685599933871

agent-token Optional

agent-token 是为了授权 ISV 调用接口，由 Antom 分配的令牌。当处理由 ISV 发起的接口请求时，Antom 会验证 agent-token 的有效性。

注意事项:

• 在 Antom Dashboard 中获取此参数的值。  
• 目前，Antom Dashboard 自动生成的 agent-token 是一个 48 位的字符串，而此参数的最大长度为 128 位。

请求体

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

响应结构

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

图2. 响应结构 

响应头部

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

注意: 字段名称不区分大小写。

表3. 响应头

每个头字段的详细信息，请参阅以下描述。

signature Required

signature 包含由逗号(,)分隔的键值对。每个键值对是一个等式，由键和值用等号(=)连接。有关生成签名的详细信息，请参阅生成签名部分。

可以配置以下键： 

• 算法 : 指定用于生成签名的数字签名算法。 支持 RSA256。
• 密钥版本: 指定用于生成或验证签名的密钥版本。默认情况下，该值为与 Client-Id 关联的最新密钥版本。
• 签名 : 包含请求的签名值。

示例：

Signature: algorithm=RSA256, keyVersion=1,
signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR
rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT
pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr
bRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%
2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3D

Content-Type Optional

Content-Type 表示 RFC2616 中定义的请求正文的媒体类型。其中，charset 用于生成/验证签名。

例如：

Content-Type: application/json; charset=UTF-8

client-id Required

client-id 用于标识客户端，并与用于签名的密钥相关联。有关获取 client-id 的详细信息，请参阅 Antom Dashboard 。

Response-time  Required

Response-time 指定了根据 ISO 8601 定义的响应发送时间。

注意：此字段必须精确到秒。

response-time: 2019-04-04T14:08:56+05:30

响应正文 ：

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

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

表4. 响应体

报文传输工作流程

整个交互序列如下所示：

图3. 消息传输工作流程 

整体流程

遵循整体流程调用接口。

准备工作

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

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

1. 构建请求

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

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

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

2. 发送请求

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

3. 检查响应

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

4. 检查状态码

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