基本规范

基本信息

• 所有的 API 请求必须使用 HTTPS，所有 HTTP 接口的 method 均为 POST。
• 入参、响应结果中的字段均采用驼峰命名。
• 字符集: UTF-8
• 所有的日期对象，使用 ISO 8601 所定义的格式

yyyy-MM-DDTHH:mm:ss.SSS+08:00
yyyy-MM-DDTHH:mm:ss+08:00

WARNING

请求时不应忽略服务器证书验证的错误，避免被恶意劫持。

请求参数

• 请求时需要对 HTTP Body 进行签名，并将签名结果与请求参数一起提交给服务器处理。详情参考：签名机制
• 业务参数通过 HTTP Body 提交，格式为 JSON，支持子对象。具体参数列表参看各个 API 接口具体描述。

示例：

# 实际请求参数请移步左侧菜单，参看各个接口文档说明

curl https://{{gateway_domain}}/v2/payment/create \
  -X POST \
  -H "Content-Type: application/json" \
  -H 'Authorization: V2_SHA256 appId=483f6c9c743b4a9bbd34bee0c9c81eb71,sign=7cc24c5ed4eb9b97696260c51d38ce9cf959c242922689885f8b30bc6863a019,timestamp=1715670758482,nonce=CEAE7940ADEEE91C5A1207F1BB78BE7F' \
  -d '{"key1": "value1", "key2": "value2"}'

响应格式

TIP

响应包含 HTTP 状态码、Response Header 和 Response Body，商户请根据 HTTP 状态码 和 Response Body 中的 code 进行后续业务逻辑处理。

错误信息

• 被网关成功接收并处理的请求，将返回 JSON 格式的应答消息体，HTTP 状态码为 200。
• 请求签名校验失败时，将会返回 401 状态码。
• 请求处理时发生了服务系统错误，将返回 5xx 范围内的状态码。

示例

HTTP/1.1 200 OK
Content-Type: application/json
Server: nginx/1.18.0
Date: Mon, 06 Mar 2024 12:00:00 GMT
Authorization: V2_SHA256 appId=483f6c9c743b4a9bbd34bee0c9c81eb71,sign=7cc24c5ed4eb9b97696260c51d38ce9cf959c242922689885f8b30bc6863a019,timestamp=1715670758482,nonce=CEAE7940ADEEE91C5A1207F1BB78BE7F

{
    "code": "OK",
    "errorMessage": null,
    "data": {
        "key1": "value1",
        "key2": "value2"
    }
}

User Agent

HTTP 协议要求发起请求的客户端在每一次请求中都使用 HTTP 头 User-Agent 来标识自己。建议调用方选用以下两种方式的一种：

• 使用HTTP客户端默认的 User-Agent。
• 遵循 HTTP 协议，使用自身系统和应用的名称和版本等信息，组成自己独有的 User-Agent。

平台很可能会拒绝处理无 User-Agent 的请求。

通知机制

通知分为两种通知方式。

同步通知(urlRedirect)

在用户支付成功，或者取消支付时，平台会将消费者的浏览器重定向到商户提供的 returnUrl 上，并携带相关参数。 同步通知采用 GET 方式跳转，相应的拼接参数，会对每个参数的值进行编码为 UTF-8 的 URLEncode 处理，随后进行跳转。

TIP

因同步通知可能出现用户模拟操作，或在同步通知未进行跳转时，用户手动关闭浏览器等不可控情况，导致商户造成损失，我们强烈建议商户以异步通知结果来确认订单的支付结果。

异步通知(webhook)

平台会将消费者支付结果的消息通过服务器端发送到商户提供的 notifyUrl上，并携带相关参数，以 POST 形式提交。

商户需要对结果信息进行相应验证和处理：

• 进行签名验证，以防止伪造的通知信息。
• 且必须对返回结果中的订单状态做判断，以确定订单状态。