收单 Open API 接口文档（一期）

面向收单商户。能力为 Payment Processing 中转：Checkout Session（创建 / 查询 / 列表 / 更新）与 Payment Intent（查询 / 列表）；支付完成后通过独立收单 Webhook 通知商户。

文档版本

2026-08-11

服务前缀

/open/v1/acquiring/**

凭证类型

必须使用 credential_type = ACQUIRING 的 AccessKey

Base URL

由交付环境提供，形如 https://{host}（下文路径相对该 Host）

责任边界

一期为 API / Webhook 技术中转与商户隔离；收单主体、清算、拒付、结算以合同及渠道协议为准

1. 接入前准备

1. 联系运营开通商户 acquiring_enabled（未开通时创建 / PATCH Session 返回 40315）。
2. 获取 ACQUIRING 类型 Open API 凭证：AccessKeyId + SecretKey + MerchantCode（由运营创建）。
3. 向运营配置收单 Webhook：HTTPS 回调 URL + 订阅事件（建议订阅 checkout_session.completed、payment_intent.succeeded、payment_intent.failed），妥善保存 Webhook Secret（仅创建/轮换时展示一次）。
4. 实现：请求签名（§2）、幂等 Key（创建 Session）、Webhook 验签（§11）、前端用 @slashfi/checkout-js 嵌入托管收银台（§5.6，不可直接浏览器打开 url）。

2. 鉴权与请求签名（商户 → 平台）

除健康检查外，所有请求须带签名头。

2.1 请求头

2.2 Canonical Request

用 \n（ASCII 0x0A）连接 4 行，再做 HMAC：

1. HTTP 方法（大写），如 POST
2. Servlet 路径，如 /open/v1/acquiring/checkout-sessions（不含域名与 query）
3. 规范化查询串：无参数时为空字符串
4. 请求体原始字节的 SHA-256（小写 hex）；无 body 时对空字节做哈希

Signature = hex_lower( HMAC_SHA256( UTF8(SecretKey), UTF8(CanonicalRequest) ) )

2.3 凭证范围

3. 统一响应

成功（HTTP 200）

{
  "code": "0",
  "message": "OK",
  "data": { },
  "traceId": "..."
}

业务字段均在 data 内。

失败（HTTP 4xx / 5xx）

{
  "code": "40315",
  "message": "商户未开通收单能力",
  "data": null,
  "traceId": "..."
}

请将 traceId 一并提供给支持排查。

4. 接口一览

5. 创建 Checkout Session

5.1 额外请求头

平台会改写发往渠道的幂等键，不会把商户原始 Key 透传给渠道。

5.2 请求体

未知顶层字段 → 40001。平台会在 metadata 中注入只读的商户标识、商户编码等保留字段（若有 clientOrderId 再注入订单映射字段）；商户勿写入或依赖覆写这些保留键。

5.3 请求示例

POST /open/v1/acquiring/checkout-sessions HTTP/1.1
Host: {host}
Content-Type: application/json
X-Access-Key-Id: ak_acq_xxx
X-Merchant-Code: M2026...
X-Vcc-Timestamp: 1723276800
X-Vcc-Signature: ...
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "amount": 1999,
  "currency": "usd",
  "clientOrderId": "ORD-20260810-001",
  "customMetadata": {
    "sku": "PLAN_PRO",
    "uid": "u_10086"
  }
}

5.4 成功响应 data

{
  "code": "0",
  "message": "OK",
  "data": {
    "id": "acq_checkout_xxx",
    "url": "https://app.slash.com/checkout/acq_checkout_xxx",
    "status": "open",
    "amount": 1999,
    "currency": "usd",
    "clientOrderId": "ORD-20260810-001",
    "merchantCode": "M2026...",
    "createdAt": "2026-08-10T10:00:00.000Z",
    "expiresAt": "2026-08-11T10:00:00.000Z",
    "paymentIntentId": null
  },
  "traceId": "..."
}

5.5 推荐业务流程

1. 服务端 POST 创建 Session，落库 id + clientOrderId。
2. 将 url 交给你们自己的前端页面，用 @slashfi/checkout-js 嵌入（见 §5.6）。
3. 以 Webhook completed 为准更新订单；可用 GET 查询做补偿。
4. 勿依赖用户关闭页面时机作为支付成功依据。

5.6 打开托管收银台（必须 SDK 嵌入）

不要：

• 在浏览器地址栏 / 新标签直接打开托管 url
• 用普通 <a href> 整页跳转到该 URL 当作收银台
• 把前端 onComplete 当作发货依据（履约仍以 Webhook / GET Session 为准）

正确做法：

1. 后端创建 Session，把 data.url（或 data.id，由后端再查）安全下发给前端。
2. 前端安装并加载 @slashfi/checkout-js（建议钉版本，例如 0.0.4）。
3. 调用 loadSlashCheckout() → createEmbeddedCheckoutPage({ url }) → mount('#容器')。
4. 监听 SDK 的 onComplete / onError 仅作 UI 提示；订单履约以收单 Webhook checkout_session.completed 或 GET /checkout-sessions/{id} 的 status=complete 为准。

<div id="checkout"></div>
<script type="module">
  import { loadSlashCheckout } from '@slashfi/checkout-js';

  const slashCheckout = await loadSlashCheckout();
  const checkout = await slashCheckout.createEmbeddedCheckoutPage({
    // 来自 POST /open/v1/acquiring/checkout-sessions 的 data.url
    url: checkoutSessionUrl,
    onReady: () => { /* 收银台已渲染 */ },
    onProcessing: () => { /* 支付处理中（UI） */ },
    onComplete: () => { /* 仅 UI；勿在此发货 */ },
    onError: ({ code, message }) => { console.error(code, message); },
  });
  checkout.mount('#checkout');
  // 换单前先 checkout.destroy()
</script>

约束与排障

6. 查询 Checkout Session

6.1 路径与规则

6.2 请求示例

GET /open/v1/acquiring/checkout-sessions/cs_xxx HTTP/1.1
Host: {host}
X-Access-Key-Id: ak_acq_xxx
X-Merchant-Code: M2026...
X-Vcc-Timestamp: 1723276800
X-Vcc-Signature: ...

6.3 成功响应 data

{
  "code": "0",
  "message": "OK",
  "data": {
    "id": "cs_xxx",
    "url": "https://checkout.example/cs_xxx",
    "status": "complete",
    "amount": 1999,
    "currency": "usd",
    "clientOrderId": "ORD-20260810-001",
    "merchantCode": "M2026...",
    "createdAt": "2026-08-10T10:00:00.000Z",
    "expiresAt": "2026-08-11T10:00:00.000Z",
    "paymentIntentId": "pi_xxx",
    "customMetadata": {
      "sku": "PLAN_PRO",
      "uid": "u_10086"
    },
    "config": null
  },
  "traceId": "..."
}

履约权威：Session status=complete（或 Webhook checkout_session.completed）。

7. 列出 Checkout Session

7.1 Query 参数

排序：按本地主键 id DESC（近似 newest first）。

7.2 请求示例

GET /open/v1/acquiring/checkout-sessions?limit=20&status=open HTTP/1.1
Host: {host}
X-Access-Key-Id: ak_acq_xxx
X-Merchant-Code: M2026...
X-Vcc-Timestamp: 1723276800
X-Vcc-Signature: ...

7.3 成功响应 data

{
  "code": "0",
  "message": "OK",
  "data": {
    "items": [
      {
        "id": "cs_xxx",
        "url": "https://checkout.example/cs_xxx",
        "status": "open",
        "amount": 1999,
        "currency": "usd",
        "clientOrderId": "ORD-20260810-001",
        "merchantCode": "M2026...",
        "createdAt": "2026-08-10T10:00:00.000Z",
        "expiresAt": "2026-08-11T10:00:00.000Z",
        "paymentIntentId": null
      }
    ],
    "nextCursor": "42",
    "count": 1
  },
  "traceId": "..."
}

8. 更新 Checkout Session

仅本地归属本商户且本地状态为 open 时可更新；经渠道 PATCH 成功后回写本地 amount / expiresAt。不会因 PATCH 单独出站 Webhook。

8.1 路径与门禁

8.2 请求体

amount 与 expiresAt 至少填一个。未知顶层字段 → 40001。

8.3 请求示例

PATCH /open/v1/acquiring/checkout-sessions/cs_xxx HTTP/1.1
Host: {host}
Content-Type: application/json
X-Access-Key-Id: ak_acq_xxx
X-Merchant-Code: M2026...
X-Vcc-Timestamp: 1723276800
X-Vcc-Signature: ...

{
  "amount": 2999,
  "expiresAt": "2026-08-12T12:00:00.000Z"
}

8.4 成功响应 data

字段同 §6 查询（含 customMetadata / config 若有）。

{
  "code": "0",
  "message": "OK",
  "data": {
    "id": "cs_xxx",
    "url": "https://checkout.example/cs_xxx",
    "status": "open",
    "amount": 2999,
    "currency": "usd",
    "clientOrderId": "ORD-20260810-001",
    "merchantCode": "M2026...",
    "createdAt": "2026-08-10T10:00:00.000Z",
    "expiresAt": "2026-08-12T12:00:00.000Z",
    "paymentIntentId": null,
    "customMetadata": {
      "sku": "PLAN_PRO",
      "uid": "u_10086"
    },
    "config": null
  },
  "traceId": "..."
}

9. 列出 Payment Intent

9.1 Query 参数

9.2 请求示例

GET /open/v1/acquiring/payment-intents?status=succeeded&limit=20 HTTP/1.1
Host: {host}
X-Access-Key-Id: ak_acq_xxx
X-Merchant-Code: M2026...
X-Vcc-Timestamp: 1723276800
X-Vcc-Signature: ...

9.3 成功响应 data

{
  "code": "0",
  "message": "OK",
  "data": {
    "items": [
      {
        "id": "pi_xxx",
        "status": "succeeded",
        "amount": 1999,
        "currency": "usd",
        "checkoutSessionId": "cs_xxx",
        "clientOrderId": "ORD-20260810-001",
        "createdAt": "2026-08-10T10:01:00.000Z",
        "updatedAt": "2026-08-10T10:05:00.000Z"
      }
    ],
    "nextCursor": null,
    "count": 1
  },
  "traceId": "..."
}

10. 查询 Payment Intent

对账权威：Intent status=succeeded（或 Webhook payment_intent.succeeded）。履约仍以 Session complete 为主路径。

10.1 路径与规则

10.2 请求示例

GET /open/v1/acquiring/payment-intents/pi_xxx HTTP/1.1
Host: {host}
X-Access-Key-Id: ak_acq_xxx
X-Merchant-Code: M2026...
X-Vcc-Timestamp: 1723276800
X-Vcc-Signature: ...

10.3 成功响应 data

{
  "code": "0",
  "message": "OK",
  "data": {
    "id": "pi_xxx",
    "status": "succeeded",
    "amount": 1999,
    "currency": "usd",
    "checkoutSessionId": "cs_xxx",
    "clientOrderId": "ORD-20260810-001",
    "createdAt": "2026-08-10T10:01:00.000Z",
    "updatedAt": "2026-08-10T10:05:00.000Z"
  },
  "traceId": "..."
}

11. 收单 Webhook（平台 → 商户）

11.1 HTTP 约定

11.2 签名头（与 Open API 入站算法不同）

payload = timestamp + nonce + body_raw_utf8
expected = hex_lower( HMAC_SHA256( UTF8(WebhookSecret), UTF8(payload) ) )

• body 必须用原始请求体，勿重新 JSON 序列化。
• Webhook Secret ≠ API SecretKey。
• 建议校验时间戳偏差，并对 eventId / nonce 去重。

11.3 事件类型

11.4 载荷结构（Session completed）

{
  "eventType": "merchant.webhook.acquiring.checkout_session.completed",
  "eventId": "mwh_evt_acq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "occurredAt": "2026-08-10T10:05:00.000Z",
  "merchantCode": "M2026...",
  "data": {
    "checkoutSessionId": "cs_xxx",
    "status": "complete",
    "amount": 1999,
    "currency": "usd",
    "clientOrderId": "ORD-20260810-001",
    "paymentIntentId": "pi_xxx",
    "customMetadata": {
      "sku": "PLAN_PRO",
      "uid": "u_10086"
    },
    "slashEventId": "可选，渠道侧事件 ID",
    "slashEventTimestamp": "可选"
  }
}

11.5 载荷结构（Payment Intent 终态）

{
  "eventType": "merchant.webhook.acquiring.payment_intent.succeeded",
  "eventId": "mwh_evt_acq_pi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "occurredAt": "2026-08-10T10:05:01.000Z",
  "merchantCode": "M2026...",
  "data": {
    "paymentIntentId": "pi_xxx",
    "checkoutSessionId": "cs_xxx",
    "status": "succeeded",
    "amount": 1999,
    "currency": "usd",
    "clientOrderId": "ORD-20260810-001",
    "updatedAt": "2026-08-10T10:05:00.000Z"
  }
}

同一资源同一终态的 eventId 稳定派生；商户须按 eventId 幂等。Session completed 与 Intent succeeded 可能先后到达，请按 clientOrderId / Session id 幂等履约。

12. 错误码（收单相关）

13. 限流与约束

14. 签名示例（Python）

14.1 调用 Open API（创建 Session）

import hashlib, hmac, json, time, uuid, urllib.request

BASE = "https://{host}"
AK = "YOUR_ACQUIRING_ACCESS_KEY"
SK = "YOUR_API_SECRET"
MERCHANT = "M..."

body_obj = {
    "amount": 1999,
    "currency": "usd",
    "clientOrderId": "ORD-001",
    "customMetadata": {"sku": "PLAN_PRO"},
}
body = json.dumps(body_obj, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
method = "POST"
path = "/open/v1/acquiring/checkout-sessions"
query = ""
body_hash = hashlib.sha256(body).hexdigest()
canonical = f"{method}\n{path}\n{query}\n{body_hash}"
ts = str(int(time.time()))
sig = hmac.new(SK.encode(), canonical.encode(), hashlib.sha256).hexdigest()

req = urllib.request.Request(
    BASE + path,
    data=body,
    method=method,
    headers={
        "Content-Type": "application/json",
        "X-Access-Key-Id": AK,
        "X-Merchant-Code": MERCHANT,
        "X-Vcc-Timestamp": ts,
        "X-Vcc-Signature": sig,
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
print(urllib.request.urlopen(req).read().decode())

14.2 验签收单 Webhook

import hashlib, hmac

def verify_acquiring_webhook(secret: str, timestamp: str, nonce: str, body: bytes, signature: str) -> bool:
    payload = (timestamp + nonce).encode("utf-8") + body
    expected = hmac.new(secret.encode("utf-8"), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature.lower())

15. 联调检查清单

• 使用 ACQUIRING Key，签名通过
• 未开通时创建返回 40315；开通后可创建并拿到 url
• 前端用 @slashfi/checkout-js 嵌入 url，能看到收银台；直接打开 url 出现 couldn't load（属预期）
• 同 Idempotency-Key 重放返回同一 id
• 改 body 同 Key → 40904
• 非 ACQUIRING 凭证调用本路径 → 40314
• list Session / Intent 仅见本商户数据；他商户 id → 40401
• PATCH open Session 成功；终态 / 关停分别得到 40916 / 40315
• Webhook 验签通过；按 eventId 幂等更新订单
• GET Session 完成后可查到 complete；对账可用 Intent succeeded

16. 变更记录