支付 API 结构样例

1. 接入前置：无需证件

基础咨询和技术需求登记无需身份证、护照、营业执照或证件照片，只需说明以下业务与技术信息：

• 业务类型、用户与交易场景
• 经营地区与目标市场
• 预计日/月笔数、金额区间、峰值与币种
• 收款、退款、代付、结算和对账需求
• 技术架构、回调域名与接口需求
• 技术联系人、生产变更与应急安排

无需证件不代表生产通道、额度或结算条件已经批准；这些条件仍以业务与通道评估后的书面确认为准。

2. 创建订单：请求与响应

金额建议使用十进制定点字符串，商户订单号在商户范围内保持唯一。不要根据本页推断实际接口必然包含某字段。

示例请求

POST https://api.example-processor.test/v1/orders
Content-Type: application/json
X-Merchant-Id: merchant_demo_001
X-Timestamp: 1784851200
X-Nonce: nonce_7f3a9c
X-Signature: SIGNATURE_PLACEHOLDER

{
  "merchant_order_id": "ORDER_20260724_0001",
  "amount": "1250.00",
  "currency": "PHP",
  "payment_method": "WALLET_OR_QR_EXAMPLE",
  "callback_url": "https://merchant.example.test/webhooks/payments",
  "return_url": "https://merchant.example.test/orders/ORDER_20260724_0001",
  "description": "Example order"
}

示例响应

{
  "request_id": "req_demo_a81f",
  "processor_order_id": "pay_demo_92831",
  "merchant_order_id": "ORDER_20260724_0001",
  "status": "PENDING",
  "amount": "1250.00",
  "currency": "PHP",
  "payment_url": "https://checkout.example-processor.test/pay/pay_demo_92831",
  "expires_at": "2026-07-24T16:30:00Z"
}

3. 签名串、回调验签与幂等

以下伪代码只展示“规范化请求后签名”的结构。实际算法可能不同，必须确认原始 body、字符编码、换行符、字段顺序、摘要格式、时间窗口和密钥版本。

canonicalBody = SHA256(rawRequestBody)
canonicalString = HTTP_METHOD + "\n"
  + REQUEST_PATH + "\n"
  + TIMESTAMP + "\n"
  + NONCE + "\n"
  + canonicalBody

signature = HEX(HMAC_SHA256(secret, canonicalString))

// 算法、字段顺序、编码、大小写与空值规则均以实际文档为准。

回调 payload 示例

{
  "event_id": "evt_demo_4012",
  "event_type": "payment.status_changed",
  "created_at": "2026-07-24T16:12:03Z",
  "data": {
    "processor_order_id": "pay_demo_92831",
    "merchant_order_id": "ORDER_20260724_0001",
    "status": "SUCCEEDED",
    "amount": "1250.00",
    "currency": "PHP",
    "paid_at": "2026-07-24T16:12:01Z"
  }
}

1. 先验签：使用接收到的原始请求体和约定 header，校验时间戳及 nonce，拒绝过期或签名不符请求。
2. 再幂等：以已确认唯一的 event_id 或“订单号 + 状态版本”原子落库；重复事件返回约定成功响应，不重复记账。
3. 后更新：锁定订单并验证金额、币种和允许的状态迁移。回调仅触发状态同步，账务变更应在同一事务或可恢复流程中完成。
4. 留审计：保存请求 ID、事件 ID、验签结果、原状态、新状态和处理时间；日志中不得记录密钥或完整敏感信息。

4. 订单状态机与主动查询/补单

状态名称和终态定义均为示例。只有书面文档明确允许时才能进行状态迁移；不要让迟到的处理中回调覆盖成功终态。

查询与补单建议

• 回调超时、验签失败或订单长期处理中时，按约定查询接口核对，不凭前端跳转结果入账。
• 查询采用退避、抖动和频率上限；保存每次 request ID，避免集中轮询。
• “补单”应是受审计的状态核对流程，不是无条件重新创建订单或重复支付。
• 人工修正必须双人复核，并记录证据、操作者、时间和原始/目标状态。

5. 错误响应与对账字段

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "request_id": "req_demo_f018",
  "error": {
    "code": "INVALID_PARAMETER_EXAMPLE",
    "message": "Request validation failed",
    "field": "amount"
  }
}

按 HTTP 状态、业务错误码和 request ID 分类处理。仅对书面标记为可重试的超时或服务端错误退避重试；参数错误、鉴权失败和余额/额度类结果不应盲目重试。

建议核对的对账概念字段

处理方是否提供这些字段、字段名称及费用口径均不作预设；联调前应取得对账文件样例和字段字典。

6. 上线测试矩阵与密钥安全