万里汇提供集成所需API，集成商可使用POST方法向万里汇发送HTTPS请求并接收对应的响应。下文介绍具体报文结构和报文传输流程。

版本迭代

万里汇API兼容历史版本。

环境

环境地址为:

• SG: open-sea.worldfirst.com
• EU: open-eu.worldfirst.com
• US: open-na.worldfirst.com

报文结构

在给万里汇发送解决方案相关报文之前，集成商需要认真阅读本文档并了解请求报文和响应报文的结构。此处具体介绍集成商和万里汇之间发送的报文结构、报文内容和报文传输流程。

请求报文结构

下图为请求报文的结构：

图1：请求报文结构

下例为报文结构的curl示例：

curl --location --request POST 'http://{domain_name}.com/amsin/api/v1/business/inquiryPayOrder' \
--header 'client-id: *****' \
--header 'Content-Type: application/json' \
--header 'signature: algorithm=RSA256,keyVersion=2,signature=KEhXthj4bJ801Hqw8kaLvE*****' \
--header 'request-time: now()' \
--header 'Cookie: JSESSIONID=66A1C5F430EA249ACD*****' \
--data-raw '{"paymentId":"sample_payment_id"}'

请求URL

请求url格式：https://{host}/amsin/api/v1/{restfulPath}

其中：

1. host为平台分配的标准域名；
2. restfulPath为接口的路径；

通过restfulPath可以唯一标识一个平台的接口。

请求方法

HTTP的请求方法统一为POST。

请求头信息

HTTP请求头主要包含了客户端、加验签、加解密相关的信息，请求头中的内容不区分大小写。

注意：部分API的请求头包含Access-Token 参数，用于 OAuth 授权。详见OAuth授权章节。

Client-Id

客户端ID。此字段代表了客户端身份，万里汇会用此字段关联签名算法的或加密算法的密钥。

Signature

本部分为报文签名的信息，格式为包含多个键值对的复杂结构。其中键值对中的key和value用等号(=)连接，不同键值对之间用逗号(,)连接。

可用的key如下：

• algorithm：代表了加验签所使用的算法，不区分大小写，默认值为RSA256，目前仅支持RSA256和ECC224；
• keyVersion：代表了本次加验签所使用的密钥版本，默认值为clientId所关联的最新的密钥版本；
• signature：是本次请求的签名字符串。

示例如下：

signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0****

具体加签方式参见相关文档：加签。

Content-Type

本次请求报文的类型以及字符编码信息，具体格式参见：RFC2616，其中的charset会在加验签、加解密算法中使用。

示例如下：

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

Request-Time

请求的时间。此字段采用ISO 8601 标准时间戳。如：2018-09-03T00:00:00+08:00。

请求体

请求体为JSON格式，包含了具体的业务请求信息。不同的接口中请求信息不同，具体参见各个接口的详细介绍。

响应报文结构

下图为响应报文的结构：

图2：响应报文结构

响应头信息

响应头主要包括以下信息：

注：响应头域不区分大小写。

Signature

本部分为报文签名的信息，格式为包含多个键值对的复杂结构。其中键值对中的key和value用等号(=)连接，不同键值对之间用逗号(,)连接。

可用的key如下：

• algorithm：代表加验签所使用的算法，不区分大小写，默认值为RSA256，目前仅支持RSA256和ECC224；
• keyVersion：代表本次加验签所使用的密钥版本，默认值为Client-Id所关联的最新的密钥版本；
• signature：包含本次响应的签名字符串。

Content-Type

本次请求报文的类型以及字符编码信息，具体格式参见：RFC2616，其中的charset会在加验签、加解密算法中使用。

Client-Id

客户端ID。此字段代表了客户端身份，万里汇会用此字段关联签名算法的或加密算法的密钥。

Response-time

响应的时间。此字段采用ISO 8601 标准时间戳。如：2018-09-03T00:00:00+08:00。

响应报文内容

包含业务处理或者受理的响应信息，不同业务的响应信息不同，但都会包括result参数，代表此次接口调用的结果。

当调用结果（resultStatus）为“失败(F)”或“未知 (U)”时，结果码（resultCode）代表错误码，结果信息（resultMessage）代表错误信息，可用于分析处理异常，具体参见错误码。

报文传输流程

下图为集成商调用接口并获取响应信息的流程：

图3：报文传输流程

接口调用流程

按照以下步骤调用接口：

准备工作

• 发送请求前，使用密钥对信息进行加签。
• 为避免接收到的响应信息出错，请确认：

• 确认编码正确
• 确认幂等性正确

1. 创建请求报文

• 请求报文需遵循报文的格式要求，包含Client-Id、请求时间、签名等必要信息。
• 为确保信息传输的安全性，所有请求和响应都必须完成加验签过程。

2. 发送请求报文

在完成创建请求报文之后，集成商可以向万里汇发送请求报文。

3. 接收响应信息

• 响应信息通常为JSON或XML格式，详细介绍参见响应报文结构部分。
• 集成商收到响应信息后，需要对响应报文签名进行验证。

4.确认结果状态

每个接口返回的响应信息会有所不同，但都包含result参数，代表此次接口调用的结果。若接口调用出错，则会返回错误码和错误信息，可用于分析处理异常。