OpenAPI 接入手册

面向 SaaS、ERP 与采购系统的月付交易、退款和 H5 接入协议。本文档以当前正式 OpenAPI YAML 为唯一契约源。

正式版本v1.0

签名协议V1 only

公开操作7 个

Base URLhttps://openapi.8thsheng.com

重试规则

每次 HTTP 尝试必须使用新的 X-Nonce；业务重试应保留原 Idempotency-Key，更新 Timestamp 和 Nonce 后重新签名。

四步完成首次调用

取得应用凭证

通过对接负责人开通应用，安全领取 App ID 与 AppSecret。AppSecret 只保存在服务端。

实现 V1 签名

严格按原始 Body 字节、Canonical Path 与 Canonical Query 生成签名原文。

调用 Ping 验证

先验证时钟、签名、Nonce 与幂等行为，再接入交易或退款接口。

接入业务接口

按应用授权范围接入财务概览、H5 票据、交易与退款能力。

接口是否可调用以应用实际授权为准。文档不提供收集真实 AppSecret 的在线调试器，写接口也不会生成可直接提交到生产的 Try it 请求。

月付消费接入闭环

SaaS 负责创建和查询，我方负责收银台授权、额度占用与交易终态。双方不使用支付结果回调，且任何前端跳转或消息都不直接代表支付成功。

SaaS 服务端创建订单

调用创建交易接口，传订单金额、subject 和可选 items。创建成功仅表示待确认订单成立，不会预留或扣减额度。

小程序打开收银台

SaaS 将 cashierUrl 交给小程序 web-view 打开。入口不可自行拼接，且必须在 expiresAt 前使用。

用户完成授权

用户核对订单并输入支付密码；密码通过后，平台最终原子校验并占用额度，再将交易提交为 SUCCEEDED。

H5 返回小程序

H5 只通知小程序收银台流程结束并返回上一页，不传可信支付结果。桥接失败时仍可在 H5 查看处理状态。

SaaS 服务端主动查询

小程序触发 SaaS 服务端查询 externalOrderNo。只有 SUCCEEDED 才能把 SaaS 订单标记为月付成功。

后台补查直到终态

若查询为 CREATED 或 PROCESSING，按退避策略继续补查；用户未返回、网络中断或首次查询丢失都不能让订单永久悬挂。

异常处理边界

创建请求超时应使用原业务键幂等重试；用户取消或入口过期不能判成功； PROCESSING 表示平台正在收敛额度与交易状态，SaaS 应继续查询； FAILED 或 CLOSED 才是明确未完成。

<!-- 小程序订单页 -->
<web-view src="{{cashierUrl}}" bindmessage="onCashierMessage" />

// 小程序订单页 JS
Page({
  async onCashierMessage(event) {
    const messages = event.detail?.data ?? [];
    const message = messages[messages.length - 1];
    if (message?.type !== "EIGHTHPAY_CASHIER_FINISHED") return;

    // 只把事件作为触发器；按本页保存的 externalOrderNo 请求 SaaS 后端。
    // AppSecret 和 8号月付 OpenAPI 签名不得放入小程序。
    await this.refreshOrderFromSaasBackend(this.data.externalOrderNo);
  }
});

V1 签名

所有请求都必须携带以下 6 个请求头。签名应在合作方服务端生成，不得把 AppSecret 下发到浏览器、小程序或移动客户端。

字段	位置	类型	必填	约束与说明
`X-App-Id`	Header	string	是	1–64 字符平台分配的应用标识。
`X-Timestamp`	Header	string	是	Unix 秒或毫秒，服务端时间窗 ±300 秒生成签名时的当前时间戳。
`X-Nonce`	Header	string	是	1–128 字符；每次 HTTP 尝试必须唯一防重放随机串。重试时必须重新生成。
`X-Signature`	Header	string	是	64 位十六进制使用 AppSecret 对 V1 签名原文执行 HmacSHA256。
`X-Signature-Version`	Header	string	是	固定为 v1当前生产公开契约只接受 V1。
`Idempotency-Key`	Header	string	是	1–128 字符；同一业务意图保持不变业务幂等键。重试时复用，但要更换 Nonce 并重新签名。

签名原文

以下 9 行使用换行符连接，空 Query 也必须保留空行。HTTP Method 使用大写；Body Hash 基于实际发送的原始 UTF-8 字节计算。

V1
{appId}
{timestamp}
{nonce}
{idempotencyKey}
{HTTP_METHOD}
{canonicalPath}
{canonicalQuery}
{sha256Hex(rawBodyBytes)}

import { createHash, createHmac, randomUUID } from "node:crypto";

const appId = process.env.EIGHTHPAY_APP_ID;
const appSecret = process.env.EIGHTHPAY_APP_SECRET;
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = randomUUID();
const idempotencyKey = "trade-SO-20260725-0001";
const method = "POST";
const canonicalPath = "/openapi/v1/trades";
const canonicalQuery = "";
const rawBody = JSON.stringify(requestBody);
const bodyHash = createHash("sha256")
  .update(Buffer.from(rawBody, "utf8"))
  .digest("hex");

const signingText = [
  "V1", appId, timestamp, nonce, idempotencyKey,
  method, canonicalPath, canonicalQuery, bodyHash
].join("\n");

const signature = createHmac("sha256", appSecret)
  .update(signingText, "utf8")
  .digest("hex");

Canonical Query

Query 名称和值按 RFC 3986 编码后排序。请先确定最终请求字节再签名；签名后重新序列化 JSON、改变空格或字段顺序都会导致校验失败。

幂等与重试

业务键保持稳定

同一次业务操作始终复用相同 Idempotency-Key、外部订单号或外部退款号。

每次尝试更换 Nonce

网络超时后重新生成 Timestamp 与 Nonce，使用原业务键和原业务参数重新签名。

不要改变业务意图

同一业务键对应的规范化参数发生变化时返回 409，不要通过换键绕过冲突。

未知结果先查询

写请求超时后先按原业务键安全重试，再使用查询接口确认权威状态。

错误处理

先按 HTTP 状态进行通用分流，再按响应体 code 处理具体原因。只有 HTTP 2xx、success=true 且 code="0"同时成立才判定成功。所有失败响应使用统一 Envelope；排查问题时请保存 traceId，不要提交 AppSecret、完整签名或 Nonce。

HTTP	响应体 code	含义	建议处理
`400`	`400`	请求不正确	请求头、JSON 格式或字段约束不正确。修正请求后再调用。
`401`	`OPENAPI_401`	身份校验失败	检查 AppId、时间、签名和 Nonce 后重新发起请求。
`403`	`403`	权限或来源受限	申请接口权限或修正调用来源；不要自动重试。
`404`	`404`	资源不存在	确认外部订单号、退款号及其 AppId 归属。
`405`	`405`	请求方法不支持	改用接口文档规定的 GET 或 POST 方法。
`406`	`406`	响应格式不可接受	将 Accept 设置为 application/json。
`409`	`409 / OPENAPI_409 / STORE_BINDING_REQUIRED`	业务冲突	保持原业务键，先查询现有结果；修正冲突后再调用。
`413`	`413`	请求内容过大	缩小请求体后重新签名并调用。
`415`	`415`	请求媒体类型不支持	将 Content-Type 设置为 application/json。
`422`	`CREDIT_NOT_GRANTED / CREDIT_UNAVAILABLE / CREDIT_INSUFFICIENT / TRADE_STATUS_CONFLICT`	业务条件不满足	按业务码引导授信、额度或交易状态处理；不要盲目重试。
`429`	`RATE_LIMITED / 429`	超过调用配额	遵循 Retry-After，保留业务键并以新 Nonce 退避重试。
`500`	`500`	服务端异常	结果可能不确定；保留 traceId，先查询业务结果再决定是否重试。
`503`	`503 / RATE_LIMIT_UNAVAILABLE`	依赖暂不可用	使用原业务幂等键、新 Timestamp 与 Nonce，按退避策略重试。

{
  "success": false,
  "code": "OPENAPI_409",
  "message": "幂等请求参数冲突",
  "data": null,
  "traceId": "f3a87d9b...",
  "timestamp": "2026-07-25T10:20:00+08:00"
}

API Reference7 个正式接口

连通性与签名验证

用于验证应用凭证、V1 签名、时间同步、Nonce 与幂等处理。建议把它作为接入第一步。

POST/openapi/v1/ping

需要 V1 签名需要幂等键

请求参数

除下表参数外，必须携带 6 个公共请求头。请求 JSON 不接受未声明字段。

字段	位置	类型	必填	约束与说明
`message`	Body	string	否	最长 256 字符原样回显的联调消息。
`externalRequestNo`	Body	string	否	最长 64 字符调用方请求编号，便于联调追踪。

curl --request POST 'https://openapi.8thsheng.com/openapi/v1/ping' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --header 'X-Timestamp: 1784912400' \
  --header 'X-Nonce: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'X-Signature-Version: v1' \
  --header 'X-Signature: YOUR_V1_SIGNATURE' \
  --header 'Idempotency-Key: ping-20260725-0001' \
  --data '{
    "message": "hello",
    "externalRequestNo": "REQ-202607250001"
  }'

{
  "success": true,
  "code": "0",
  "message": "success",
  "data": {
    "appId": "YOUR_APP_ID",
    "message": "hello",
    "requestNo": "REQ-202607250001",
    "traceId": "f3a87d9b..."
  },
  "traceId": "f3a87d9b...",
  "timestamp": "2026-07-25T10:20:00+08:00"
}

幂等与重试

网络失败时复用原 Idempotency-Key，生成新的 Timestamp 与 Nonce 后重新签名。

可能状态码

200 400 401 403 405 406 409 413 415 429 500 503

查询商户财务概览

按调用方的外部客户编号查询注册、授信、额度与下一期待还摘要。数据范围由应用归属决定。

POST/openapi/v1/merchant-finance-overviews/query

需要 V1 签名需要幂等键

接入注意

DEFAULT_REFERENCE 是系统参考额度，不表示客户已获得授信；只有 AVAILABLE_CREDIT 才表示真实可用额度。

请求参数

除下表参数外，必须携带 6 个公共请求头。请求 JSON 不接受未声明字段。

字段	位置	类型	必填	约束与说明
`externalCustomerNo`	Body	string	是	1–128 字符调用方体系内稳定且唯一的客户编号。

curl --request POST 'https://openapi.8thsheng.com/openapi/v1/merchant-finance-overviews/query' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --header 'X-Timestamp: 1784912400' \
  --header 'X-Nonce: NEW_UNIQUE_NONCE' \
  --header 'X-Signature-Version: v1' \
  --header 'X-Signature: YOUR_V1_SIGNATURE' \
  --header 'Idempotency-Key: overview-MERCHANT-10086' \
  --data '{
    "externalCustomerNo": "MERCHANT-10086"
  }'

{
  "success": true,
  "code": "0",
  "message": "success",
  "data": {
    "merchantState": "CREDITED_NO_ACTIVE_LOAN",
    "registrationStatus": "REGISTERED",
    "creditStatus": "CREDITED",
    "loanStatus": "NO_ACTIVE_LOAN",
    "limit": {
      "amountType": "AVAILABLE_CREDIT",
      "displayAmount": { "amount": "50000.00", "currency": "CNY" },
      "totalLimit": { "amount": "50000.00", "currency": "CNY" },
      "availableAmount": { "amount": "50000.00", "currency": "CNY" },
      "usedAmount": { "amount": "0.00", "currency": "CNY" }
    },
    "repayment": null
  },
  "traceId": "f3a87d9b...",
  "timestamp": "2026-07-25T10:20:00+08:00"
}

幂等与重试

查询重试仍需保留原 Idempotency-Key，并为每次 HTTP 尝试生成新的 Nonce。

可能状态码

200 400 401 403 405 406 413 415 429 500 503

签发 H5 入口票据

按大 B 体系内的小 B 商户与用户标识签发短时、一次性 H5 入口票据；商户尚未映射时会按请求信息完成基础注册。

POST/openapi/v1/h5/entry-tickets

需要 V1 签名需要幂等键敏感响应 · no-store

接入注意

externalUserNo 是稳定用户身份。相同应用、商户和 externalUserNo 再次传入新手机号时更新原账号手机号，不会创建新用户。entryToken 是短时一次性敏感凭证，只能使用完整 entryUrl 跳转。

请求参数

除下表参数外，必须携带 6 个公共请求头。请求 JSON 不接受未声明字段。

字段	位置	类型	必填	约束与说明
`externalMerchantNo`	Body	string	是	1–128 字符大 B 系统中的小 B 商户稳定编号。
`merchantName`	Body	string	是	1–128 字符小 B 商户名称；当前经营模型下同时作为默认门店名称。
`externalUserNo`	Body	string	是	1–128 字符大 B 系统中的小 B 用户稳定编号；用于识别同一用户。
`mobile`	Body	string	是	中国大陆手机号用户当前手机号；同一 externalUserNo 传入新手机号时更新原账号。
`scene`	Body	string	是	固定为 HOME入口业务场景。
`businessType`	Body	string	否	最长 64 字符可选业务类型。
`businessNo`	Body	string	否	最长 64 字符可选业务编号。
`redirectPath`	Body	string	是	固定为 /homeH5 兑换后的目标页面。
`nonce`	Body	string	是	1–128 字符票据业务随机串，与请求头 X-Nonce 相互独立。

curl --request POST 'https://openapi.8thsheng.com/openapi/v1/h5/entry-tickets' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --header 'X-Timestamp: 1784912400' \
  --header 'X-Nonce: NEW_UNIQUE_NONCE' \
  --header 'X-Signature-Version: v1' \
  --header 'X-Signature: YOUR_V1_SIGNATURE' \
  --header 'Idempotency-Key: h5-MERCHANT-10086-USER-20001-0001' \
  --data '{
    "externalMerchantNo": "MERCHANT-10086",
    "merchantName": "示例商户",
    "externalUserNo": "USER-20001",
    "mobile": "13800138000",
    "scene": "HOME",
    "redirectPath": "/home",
    "nonce": "ticket-business-nonce-0001"
  }'

{
  "success": true,
  "code": "0",
  "message": "success",
  "data": {
    "ticketNo": "TK202607250001",
    "entryToken": "ONE_TIME_ENTRY_TOKEN",
    "expiresAt": "2026-07-25T10:30:00+08:00",
    "entryUrl": "https://h5.example.com/entry?entryToken=..."
  },
  "traceId": "f3a87d9b...",
  "timestamp": "2026-07-25T10:20:00+08:00"
}

幂等与重试

相同业务意图使用相同 Idempotency-Key。有效期内会返回首次结果；请求变化或原结果过期返回 409，不会签发第二张票据。

可能状态码

200 400 401 403 405 406 409 413 415 429 500 503

创建月付交易

创建待确认月付交易并取得一次性 H5 收银台地址。创建时只校验授信与当前可用额度，不预留或占用额度。

POST/openapi/v1/trades

需要 V1 签名需要幂等键敏感响应 · no-store

接入注意

平台不接收 returnUrl 或 notifyUrl，也不发送支付结果回调。小程序返回后，SaaS 服务端必须主动查询交易状态。

请求参数

除下表参数外，必须携带 6 个公共请求头。请求 JSON 不接受未声明字段。

字段	位置	类型	必填	约束与说明
`externalCustomerNo`	Body	string	是	1–128 字符调用方体系内稳定的客户编号。
`externalOrderNo`	Body	string	是	1–64 字符；应用内唯一调用方外部订单号。
`amount`	Body	number	是	0.01–9999999999999999.99，最多 2 位小数交易金额。
`currency`	Body	string	是	固定为 CNY交易币种。
`subject`	Body	string	是	1–128 字符收银台和交易记录展示的订单标题；多商品可使用“办公用品等 3 件商品”一类合集摘要。
`items[]`	Body	array<object>	否	最多 50 行；行金额合计必须等于订单金额商品明细快照。每行包含 name、quantity、amount，可选 externalItemNo；amount 是该行折后合计，不是单价。

curl --request POST 'https://openapi.8thsheng.com/openapi/v1/trades' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --header 'X-Timestamp: 1784912400' \
  --header 'X-Nonce: NEW_UNIQUE_NONCE' \
  --header 'X-Signature-Version: v1' \
  --header 'X-Signature: YOUR_V1_SIGNATURE' \
  --header 'Idempotency-Key: trade-SO-20260725-0001' \
  --data '{
    "externalCustomerNo": "MERCHANT-10086",
    "externalOrderNo": "SO-20260725-0001",
    "amount": 100.00,
    "currency": "CNY",
    "subject": "办公用品等 2 件商品",
    "items": [
      {
        "externalItemNo": "SKU-A4-PAPER",
        "name": "A4 打印纸",
        "quantity": 2,
        "amount": 60.00
      },
      {
        "externalItemNo": "SKU-TONER",
        "name": "打印机硒鼓",
        "quantity": 1,
        "amount": 40.00
      }
    ]
  }'

{
  "success": true,
  "code": "0",
  "message": "success",
  "data": {
    "tradeNo": "TR202607250001",
    "externalOrderNo": "SO-20260725-0001",
    "status": "CREATED",
    "cashierUrl": "https://h5.example.com/cashier?entryToken=...",
    "expiresAt": "2026-07-25T10:30:00+08:00"
  },
  "traceId": "f3a87d9b...",
  "timestamp": "2026-07-25T10:20:00+08:00"
}

幂等与重试

创建超时或响应丢失时，复用相同 Idempotency-Key、externalOrderNo 和完整业务参数重试。相同意图返回原交易与原收银台入口；参数变化返回 409。

可能状态码

200 400 401 403 405 406 409 413 415 422 429 500 503

查询月付交易

按外部订单号查询交易权威状态。这是 SaaS 判断月付结果的唯一开放接口；H5 返回或小程序消息都不能作为成功凭证。

GET/openapi/v1/trades/{externalOrderNo}

需要 V1 签名需要幂等键

接入注意

只有 SUCCEEDED 表示用户授权成功、额度占用成功且月付消费订单成立。CREATED 或 PROCESSING 必须继续后台补查。

请求参数

除下表参数外，必须携带 6 个公共请求头。请求 JSON 不接受未声明字段。

字段	位置	类型	必填	约束与说明
`externalOrderNo`	Path	string	是	1–64 字符创建交易时使用的外部订单号。

curl --request GET \
  'https://openapi.8thsheng.com/openapi/v1/trades/SO-20260725-0001' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --header 'X-Timestamp: 1784912400' \
  --header 'X-Nonce: NEW_UNIQUE_NONCE' \
  --header 'X-Signature-Version: v1' \
  --header 'X-Signature: YOUR_V1_SIGNATURE' \
  --header 'Idempotency-Key: query-trade-SO-20260725-0001'

{
  "success": true,
  "code": "0",
  "message": "success",
  "data": {
    "tradeNo": "TR202607250001",
    "externalOrderNo": "SO-20260725-0001",
    "amount": "100.00",
    "currency": "CNY",
    "status": "SUCCEEDED",
    "subject": "办公用品等 2 件商品",
    "items": [
      {
        "externalItemNo": "SKU-A4-PAPER",
        "name": "A4 打印纸",
        "quantity": 2,
        "amount": "60.00"
      },
      {
        "externalItemNo": "SKU-TONER",
        "name": "打印机硒鼓",
        "quantity": 1,
        "amount": "40.00"
      }
    ],
    "createdAt": "2026-07-25T10:20:00+08:00",
    "completedAt": "2026-07-25T10:21:00+08:00"
  },
  "traceId": "f3a87d9b...",
  "timestamp": "2026-07-25T10:21:00+08:00"
}

幂等与重试

用户回到小程序后由 SaaS 服务端立即查询；若为 CREATED 或 PROCESSING，采用退避轮询并进入后台补查。每次查询使用新的 Nonce，签名 Body Hash 使用空 Body 的 SHA-256。

可能状态码

200 400 401 403 404 405 406 429 500 503

创建退款

针对当前应用创建的原交易发起退款。退款受原交易归属、可退金额与业务状态约束。

POST/openapi/v1/refunds

需要 V1 签名需要幂等键

请求参数

除下表参数外，必须携带 6 个公共请求头。请求 JSON 不接受未声明字段。

字段	位置	类型	必填	约束与说明
`externalOrderNo`	Body	string	是	1–64 字符当前应用创建的外部订单号。
`externalRefundNo`	Body	string	是	1–64 字符；应用内唯一调用方稳定且唯一的外部退款号。
`amount`	Body	number	是	不小于 0.01，最多 2 位小数本次退款金额。
`currency`	Body	string	是	固定为 CNY退款币种。
`reasonCode`	Body	string	否	最长 64 字符调用方退款原因码。
`reason`	Body	string	否	最长 512 字符退款原因说明。

curl --request POST 'https://openapi.8thsheng.com/openapi/v1/refunds' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --header 'X-Timestamp: 1784912400' \
  --header 'X-Nonce: NEW_UNIQUE_NONCE' \
  --header 'X-Signature-Version: v1' \
  --header 'X-Signature: YOUR_V1_SIGNATURE' \
  --header 'Idempotency-Key: refund-RF-20260725-0001' \
  --data '{
    "externalOrderNo": "SO-20260725-0001",
    "externalRefundNo": "RF-20260725-0001",
    "amount": 50.00,
    "currency": "CNY",
    "reasonCode": "CUSTOMER_REQUEST",
    "reason": "客户申请部分退款"
  }'

{
  "success": true,
  "code": "0",
  "message": "success",
  "data": {
    "refundNo": "RF202607250001",
    "externalRefundNo": "RF-20260725-0001",
    "tradeNo": "TR202607250001",
    "externalOrderNo": "SO-20260725-0001",
    "amount": 50.00,
    "currency": "CNY",
    "status": "PROCESSING",
    "billReductionAmount": null,
    "creditRestoreAmount": null,
    "cashRefundAmount": null,
    "requestedAt": "2026-07-25T10:30:00+08:00",
    "succeededAt": null
  },
  "traceId": "f3a87d9b...",
  "timestamp": "2026-07-25T10:30:00+08:00"
}

幂等与重试

相同 Idempotency-Key 或 externalRefundNo 必须对应完全相同的请求。参数一致时返回同一退款事实，变化时返回 409。

可能状态码

200 400 401 403 404 405 406 409 413 415 422 429 500 503

查询退款

按外部退款号查询当前应用范围内的退款状态与账单冲减、额度恢复、现金退款结果。

GET/openapi/v1/refunds/{externalRefundNo}

需要 V1 签名需要幂等键

接入注意

退款 status 是可扩展字段。客户端应兼容未来新增状态，并把未知状态视为处理中后主动查询，不能按固定枚举直接判定成功。

请求参数

除下表参数外，必须携带 6 个公共请求头。请求 JSON 不接受未声明字段。

字段	位置	类型	必填	约束与说明
`externalRefundNo`	Path	string	是	1–64 字符创建退款时使用的外部退款号。

curl --request GET \
  'https://openapi.8thsheng.com/openapi/v1/refunds/RF-20260725-0001' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --header 'X-Timestamp: 1784912400' \
  --header 'X-Nonce: NEW_UNIQUE_NONCE' \
  --header 'X-Signature-Version: v1' \
  --header 'X-Signature: YOUR_V1_SIGNATURE' \
  --header 'Idempotency-Key: query-refund-RF-20260725-0001'

{
  "success": true,
  "code": "0",
  "message": "success",
  "data": {
    "refundNo": "RF202607250001",
    "externalRefundNo": "RF-20260725-0001",
    "tradeNo": "TR202607250001",
    "externalOrderNo": "SO-20260725-0001",
    "amount": 50.00,
    "currency": "CNY",
    "status": "SUCCEEDED",
    "billReductionAmount": 50.00,
    "creditRestoreAmount": 50.00,
    "cashRefundAmount": 0.00,
    "requestedAt": "2026-07-25T10:30:00+08:00",
    "succeededAt": "2026-07-25T10:31:00+08:00"
  },
  "traceId": "f3a87d9b...",
  "timestamp": "2026-07-25T10:32:00+08:00"
}

幂等与重试

查询重试复用业务 Idempotency-Key，并使用新的 Nonce。退款状态应以查询接口的最新结果为准。

可能状态码

200 400 401 403 404 405 406 429 500 503

业务状态

交易状态

CREATED已创建，等待客户确认；尚未占用额度

PROCESSING授权处理中或状态正在收敛，继续查询

SUCCEEDED授权和额度占用均成功，月付消费成立

FAILED交易失败，不得按成功处理

CLOSED用户未完成或入口过期，交易已关闭

REFUNDED交易已退款

退款状态向前兼容

退款 status 不是闭合枚举。客户端必须容忍新增状态；未识别状态不能直接映射为失败，应保留原值并主动查询。

公共响应结构

字段	位置	类型	必填	约束与说明
`success`	Body	boolean	是	成功为 true，失败为 false请求处理结果。
`code`	Body	string	是	成功固定为 "0"；失败见错误码表稳定的机器可读业务码。HTTP 状态用于通用分流，code 用于具体处理。
`message`	Body	string	是	已脱敏面向调用方的结果说明。
`data`	Body	object \| null	是	接口专属结构成功业务数据；失败时通常为 null。
`traceId`	Body	string	是	全链路追踪标识联调和故障排查必须保留。
`timestamp`	Body	date-time	是	RFC 3339服务端响应时间。

联调与支持

申请开通

联系既有商务或项目对接负责人，提交接入主体、业务场景、所需接口与预计调用量。

问题反馈

提供环境、时间、operationId、外部业务号和 traceId；请勿发送 AppSecret、完整签名、Nonce 或敏感业务数据。

正式契约

以版本化 YAML 为准。经营数据等 Preview 能力不属于当前正式公开接口。

下载 OpenAPI 3.0 YAML

更新记录

2026-07-31v1.0 月付交易契约勘误

创建交易改用 subject 和可选 items 商品快照；移除 returnUrl；明确创建时不占用额度、平台不发送支付结果回调，SaaS 以主动查询的 SUCCEEDED 为成功依据。

2026-07-28v1.0 勘误

明确成功业务码固定为 0；补齐响应体错误码目录及 405、406、413、415 标准 HTTP 状态。

2026-07-25v1.0

对齐 7 个正式接口；生产公开契约固定为 V1 签名；补齐交易、退款、 H5 票据的幂等与错误语义。