请求与响应
- Open APIs的
HTTP method均为POST； - 请求的
Header的Accept均为application/json，Content-Type为application/json； - 请求的
Body格式为JSON; - 系统使用
UTF-8字符集。
请求结构
每个Request都包含Request URL, Method, Header 和 Body。
URL
请求的URL格式为https://{domain name}/api/{version}/{endpoint}，包含如下部分：
domain name: AlphaPay Open API平台域名, 如openapi.alphapay.ca。version: API版本号，如v1.0或v2.0。endpoint: 指定具体的接口名称，如：/{version}/payments/pay。一个接口是被endpoint唯一标识的，如：/v1.0/payments/pay是和/v2.0/payments/pay不同的接口。完整的URL示例：https://openapi.alphapay.ca/api/v2.0/payments/pay。
Method
均为POST
Request Header
所有请求的Request Header均会包含以下几个字段。
注意：字段名是大小写敏感的。
| 字段 | 必填 | 描述 | 示例 |
|---|---|---|---|
Signature | Yes | 签名信息 | Signature: algorithm=RS256, keyVersion=1, signature={generatedSignature} |
Merchant-Code | Yes | AlphaPay平台提供的商户号 | Merchant-Code: CXVJIU |
Request-Time | Yes | 请求时间，为ISO8601标准，必须精确到秒 | Request-Time: 2019-04-04T12:08:56+05:30 |
Nonce | Yes | 随机字符串，长度为32 | Nonce: b111bcf0dfb54d4e8bae68c293d85e2e |
Content-Type | Yes | 请求的媒体类型 | Content-Type: application/json; charset=UTF-8 |
Accept | Yes | 可接收的媒体类型 | Accept: application/json |
Signature
Signature是由多个键值对(key-value pairs)组成，每个键值对的格式为{key}={value}，如algorithm=RS256；两个键值对之间用半角逗号,连接，如algorithm=RS256,keyVersion=1。
以下是Signature所需的key：
algorithm：指定用于生成签名的签名算法，默认是RS256。keyVersion：指定本次请求使用的用于生成签名和验证签名的key的版本号，目前为1。signature：完整的请求的签名信息，生成方法的详情请参考签名算法。
一个完整的Signature如下：
Signature: algorithm=RS256, keyVersion=1, signature=d%2FqFC126U57guKgRRXnd4colw5Ed5tpq3NDh2M5JOtfDivAze4X%2BYEaUCWHNW7h02sSed7hsnsDtM2rjtYe8kqAJTV9fMLzraeUZvWBh4j8Sf2D%2Bcz4bJ23S4F7VtoWaxMWjySwWuS0nMQweg%2BM7MY1HQFz2EXZjAa4CVflxU1I61NuEURfiYJGW%2BLEf%2FPVPEgzBLO8LopYMovmgO7Fl97E9UVFZnFW37bSaEdkNCffJlBU00AYWKaXbsARLarETkY9NA8nTJ5yDwjKm4rH3O%2FUhwGYnwLAvozKKjfWLU4m15LoAUF30Tap6d7IGFfewnLxdY34sVYG3Nx6m0Mit%2Bg%3D%3D
Merchant-Code
Merchant-Code商户编码是商户在AlphaPay的唯一ID，会用于请求的签名生成。Merchant-Code长度为4-6位，在商户后台中可以查看。例如：Merchant-Code: CXVJIU。
Request-Time
请求时间指定了请求的时间，格式为ISO8601。
需要精确到秒，例如：Request-Time: 2019-04-04T12:08:56+05:30。
Nonce
随机生成的字符串，长度为32位。例如：Nonce: b111bcf0dfb54d4e8bae68c293d85e2e。
Content-Type
Content-Type指明了请求body的媒体类型。例如：Content-Type: application/json; charset=UTF-8。
Accept
Accept指明了请求可接收的的媒体类型。例如：Accept: application/json。
Request Body
请求的Request Body为JSON格式，包含了详细的请求信息。具体的信息需要查看具体的API说明。
响应结构
每个Response都包含Header, Body 和 response status。
Response Header
所有响应的Response Header均会包含以下几个字段。
注意：字段名是大小写敏感的。
| 字段 | 必填 | 描述 | 示例 |
|---|---|---|---|
Signature | Yes | 签名信息 | Signature: algorithm=RS256, keyVersion=1, signature={generatedSignature} |
Merchant-Code | Yes | AlphaPay平台提供的商户号 | Merchant-Code: CXVJIU |
Response-Time | Yes | 响应时间，为ISO8601标准，必须精确到秒 | Response-Time: 2019-04-04T12:08:56+05:30 |
Nonce | Yes | 随机字符串，长度为32 | Nonce: b111bcf0dfb54d4e8bae68c293d85e2e |
Content-Type | Yes | 响应的媒体类型 | Content-Type: application/json; charset=UTF-8 |
Signature，Merchant-Code，Response-Time，Nonce和Content-Type与请求头的规范保持一致。
Response Body
响应的Body包含了需要响应给客户端的消息，字段根据具体的服务返回不同的信息，但是指明API调用结果的result字段是每个接口都会返回的。 如果API调用失败时，resultCode通常会返回一个错误码，resultMessage会返回一个错误消息，这些可以用来诊断错误。
| 字段 | 类型 | 描述 |
|---|---|---|
resultCode | String | 业务结果码，详情查看业务结果码 (resultCode) |
resultStatus | String | 业务结果状态，详情查看业务结果状态 (resultStatus) |
Response-Time | String | 结果消息，详细的错误信息 |
请求流程
1. 构建请求
遵循请求结构的文档来构建请求。
以确保请求的安全性和真实性，所有请求都需按要求添加签名，详情请参考签名算法。
2. 发送请求
发送上一步构建好且带有签名的请求。
3. 接收并验证响应
响应会返回JSON格式的数据，具体格式请参考响应结构。
以确保响应的安全性和真实性，所有响应都附带签名，详情请参考签名算法。在做业务的处理前需先验证签名有效性。
4. 检查并处理业务结果
响应会根据请求具体的服务返回不同的信息，但是指明API调用结果的result字段是每个接口都会返回的。
如果API调用失败时，resultCode会返回一个错误码，resultMessage会返回一个错误消息，这些可以用来诊断错误。
如没有出现错误则可以进行业务的处理。
安全传输层协议
仅支持TLS 1.2。