开发文档

接口清单与接入范围

以下路径均相对于 /api/v1/gateway，统一使用 POST application/json 和 RSA2 签名信封。接口存在不等于商户已获操作权限；实际能力取决于商户、用户组、通道和插件配置。

除“请求信封”和“响应信封”示例外，各接口的 JSON 示例均为 biz_content，发送前必须包装并签名。示例编号、金额、日期和地址仅供说明，不能原样用于正式交易。

接入准备

1. 完成商户入驻与必要的实名认证，确认账户、支付权限和所需支付方式已启用。
2. 登录商户中心 → RSA 密钥，准备 AppID、商户应用私钥及对应公钥；平台保存应用公钥以验证请求。
3. 获取平台公钥，用于验证响应和通知。当前账户的网关及密钥信息见接口资料。
4. 准备公网可访问的 HTTPS 通知地址，并按账户要求登记通知、回跳域名及服务端请求 IP。

请求网关

平台尚未配置接口域名，请联系运营人员。不要使用当前页面域名或管理后台地址自行拼接网关。

下文接口路径均追加在上述网关之后。所有商户主动请求使用 POST 和 Content-Type: application/json，由服务端发送。

请求与 RSA2 签名

外层固定为以下 7 个字段，业务参数只放在 biz_content。接口不接受未知业务字段或尾随的第二段 JSON。

{
  "app_id": "YOUR_APP_ID",
  "version": "1.0",
  "sign_type": "RSA2",
  "timestamp": 1767225600,
  "date": "2026-01-01T00:00:00Z",
  "biz_content": {"merchant_order_no":"DEMO_ORDER_001"},
  "sign": "BASE64_SIGNATURE"
}

这是结构示例，不可直接发送。替换 AppID、业务参数和当前时间，重新签名。示例中的固定时间已经过期。

生成签名原文

1. 排除外层 sign，其余字段名按升序排序。sign_type 和 date 参与签名。
2. 字符串字段取解码后的原值，不带 JSON 引号；整数保留十进制文本。空字符串值不参与拼接，数值 0 不能省略。
3. biz_content 使用待发送或实际收到的原始 JSON，仅删除字符串外的无意义空白；保留字段顺序、转义形式和数字写法，不要解析后重新序列化。
4. 将字段拼成 key=value，用 & 连接，不做 URL 编码，不附加换行。
5. 对原文 UTF-8 字节使用 SHA-256 + RSA PKCS#1 v1.5 签名，再作 Base64 编码；不是 RSA-PSS。RSA 公钥至少 2048 位。

app_id=YOUR_APP_ID&biz_content={"merchant_order_no":"DEMO_ORDER_001"}&date=2026-01-01T00:00:00Z&sign_type=RSA2&timestamp=1767225600&version=1.0

相同签名会被重放保护拒绝。重试须保持原商户订单号与业务参数，刷新时间并重新签名；不要原样重发请求信封。

验证平台响应

签名响应包含 app_id、version、sign_type、timestamp、date、code、msg、biz_content、sign。使用平台公钥按同一规则验签，code 和 msg 也参与签名；验签后校验 AppID、算法、版本和时间，再判断 HTTP 状态与 code。

code=0 表示接口调用成功，不表示订单已支付。鉴权、限流或代理错误可能没有签名信封；无签名、验签失败或网络异常都不能当作支付成功。

{
  "app_id": "YOUR_APP_ID",
  "version": "1.0",
  "sign_type": "RSA2",
  "timestamp": 1767225600,
  "date": "2026-01-01T00:00:00Z",
  "code": 0,
  "msg": "ok",
  "biz_content": {"trace_id":"TRACE_ID"},
  "sign": "BASE64_RESPONSE_SIGNATURE"
}

上例只展示外层结构；实际 biz_content 由对应接口决定。响应中的可选字段可能省略，未知新增字段应兼容，但未知业务状态不能当作成功。时间字段为 RFC3339；未发生的事件时间可能省略或为零值时间，不能仅凭时间字段推断成功。

金额、时间与幂等

金额与手续费使用币种最小单位的整数，人民币为分，不接受小数元或数字字符串。支付金额程序上限为 9000000000000，实际商户/通道限额通常更低。expire_seconds 为整数秒：省略或 0 使用平台默认；未配置时基础默认 1800 秒、范围 60～86400 秒。平台可调整默认值与范围，通道限制再取交集；默认值会调整到有效范围，显式负数或越界值会报错，以响应 expired_at 为准。

网络超时、HTTP 5xx 或响应无法验签表示“结果未知”，不等于扣款或退款失败。先按原业务单号查单；只有确认结果后才能决定后续操作。重试保留原业务编号及业务参数，刷新时间并重新签名；同一编号不能用于不同业务。

收银台接入

推荐流程：商户服务端创建会话 → 验签后将用户引导到返回的 cashier_url → 等待异步通知或服务端查单。

创建会话 · POST /cashier/session

将下列业务对象放入请求信封的 biz_content：

{
  "merchant_order_no": "DEMO_ORDER_001",
  "amount": 100,
  "currency": "CNY",
  "subject": "示例商品",
  "pay_type": "wxpay",
  "notify_url": "https://merchant.example.com/pay/notify",
  "return_url": "https://merchant.example.com/pay/return"
}

响应业务对象如下。保存会话号，核对金额与订单信息，原样使用已验签的收银台地址，不自行拼接或更换域名。

{"session_no":"SESSION_NO_FROM_RESPONSE","merchant_order_no":"DEMO_ORDER_001","amount":100,"currency":"CNY","subject":"示例商品","scene":"web_cashier","pay_type":"wxpay","cashier_url":"https://cashier.example.com/bill/session/SESSION_NO_FROM_RESPONSE","status":"created","trace_id":"TRACE_ID","expired_at":"2026-01-01T00:30:00Z","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}

查询会话 · POST /cashier/session/query

{"session_no":"SESSION_NO_FROM_RESPONSE"}

唯一请求字段 session_no：string，必填，仅可查询当前签名商户的会话。响应字段与创建会话一致。

这里展示的是 biz_content，仍需完整签名信封。会话状态包括 created、paying、paid、expired、closed；产生支付订单后返回 order_no。会话查询读取平台记录，不等同于上游主动查单；支付结果确认使用下方 /query 或有效通知。

重复创建返回原会话，不延长有效期、不重置状态；改变 expire_seconds、scene 或 client_ip 不会更新已存在的会话。订单号、应用、金额、币种、标题、说明、支付方式、通知与回跳地址须与原会话匹配。

直接下单 · POST /pay

适合需要自行展示付款入口的商户；不再调用会话创建接口。pay_type 必填，pay_mode 不传默认 native，实际场景须由商户通道支持。

{
  "merchant_order_no": "DEMO_ORDER_002",
  "pay_type": "alipay",
  "pay_mode": "native",
  "subject": "示例商品",
  "amount": 100,
  "currency": "CNY",
  "notify_url": "https://merchant.example.com/pay/notify"
}

以上为业务对象；订单号、金额、标题、通知与有效期等规则同前。不要传内部插件或通道编码。可选场景如 page、wap、native、jspay、app，以实际开通能力为准。

响应还包含 order_no、merchant_order_no、amount、currency、status。支付地址可能承载身份检查或授权步骤，通过检查、浏览器回跳和客户端提示均不能替代服务端付款确认。

支付订单响应字段

/pay、/query、/close、/cashier/pay 共用以下 biz_content 结构；字段是否出现取决于当前状态。

{"order_no":"PLATFORM_ORDER_NO","merchant_order_no":"DEMO_ORDER_002","pay_type":"alipay","pay_mode":"native","subject":"示例商品","amount":100,"currency":"CNY","fee_amount":0,"status":"paying","pay_info":"https://pay.example.com/DEMO_TOKEN","pay_info_type":"url","trace_id":"TRACE_ID","expired_at":"2026-01-01T00:30:00Z","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}

付款账号只在当前商户的签名响应、查单及支付成功通知中返回。微信 OpenID 受应用范围限制，支付宝 UID 不应当作微信 OpenID 使用；不使用其他应用的登录身份或商户自行上传的账号补全。没有可靠付款身份时原生接口省略这些字段，客户端付款账号保持 null，不猜测或填入其他身份。付款人公开收银台接口不返回这些商户身份字段。

查询订单 · POST /query

{"merchant_order_no":"DEMO_ORDER_002"}

请求字段 merchant_order_no、order_no 均为 string，两者至少提供一个；同时提供时必须指向同一订单，只能查询当前商户的订单。响应见支付订单响应字段。creating、paying、closing 等适用状态会在插件支持时主动向上游查单；authorizing 通常只返回当前记录，到期订单可能先执行本地过期处理。不支持主动查询时返回平台已有状态，不能把“查询成功”理解为上游已确认付款。

验签后核对订单号、金额、币种与支付方式。仅将 status=paid 作为付款成功处理，并保证本地交付幂等。

关闭未支付订单

关闭订单 · POST /close

取消尚未完成付款的订单。关单不是退款：已付款订单请使用退款接口。请求与响应都使用前述 RSA2 签名信封，下例仅展示 biz_content。

{
  "merchant_order_no": "DEMO_ORDER_001"
}

允许关闭的状态

仅允许 creating（创建中）、paying（待支付）、authorizing（付款人授权中）且没有付款时间、没有冻结资金、未删除的订单。资金状态还须为空或 none。已支付、已退款、已关闭、关闭处理中或受资金限制的订单会被拒绝。

尚未向通道发起支付的授权订单可直接关闭并使授权支付流程失效；其他订单要求原支付插件具备关单能力。插件或通道不支持时，不能用本接口强行关闭。

成功响应业务对象

{
  "order_no": "ACG_DEMO_ORDER_001",
  "merchant_order_no": "DEMO_ORDER_001",
  "pay_type": "wxpay",
  "pay_mode": "jspay",
  "subject": "示例商品",
  "amount": 1000,
  "currency": "CNY",
  "fee_amount": 6,
  "status": "closed",
  "trace_id": "TRACE_DEMO_ORDER_001",
  "expired_at": "2026-09-30T12:30:00+08:00",
  "paid_at": "0001-01-01T00:00:00Z",
  "created_at": "2026-09-30T12:00:00+08:00",
  "updated_at": "2026-09-30T12:01:00+08:00"
}

返回结构与下单、查单的订单对象一致。可选字段可能不出现；即使返回了历史支付信息，订单关闭后也不得继续展示或使用。

超时与重复关单

平台在请求通道前保存 closing。超时或“正在确认关闭结果”不代表关闭失败，也不代表已关闭；请使用 /query 查明最终状态，若实际已付款应进入退款流程。关闭中的订单不能立即重复关单；已关闭订单再次关单也会返回状态限制错误，所以不要要求重复调用必须返回成功，更不要因此创建新的支付订单。

退款与退款查询

支持按商户退款单号跟踪每一次退款。平台接受全额或部分退款申请，但是否支持部分退款、可退期限及其他通道限制取决于原订单使用的支付插件和通道，不能假定所有插件都支持。以下金额均为整数，人民币单位为分。

申请退款 · POST /refund

{
  "merchant_order_no": "DEMO_ORDER_001",
  "merchant_refund_no": "DEMO_REFUND_001",
  "amount": 400,
  "currency": "CNY",
  "reason": "退回部分商品"
}

受理与幂等规则

1. 原订单须为已支付状态，且资金没有被冻结；商户 API 不允许直接退审核中订单。原订单标记为 refunded 也仍需校验剩余可退款金额，不代表可以再次全额退款。
2. 同一商户、同一 merchant_refund_no、相同订单、金额、币种和原因，返回已有退款记录，不会再次发起退款。改变任一业务参数会被拒绝；已终结失败的编号也不会因为重复请求而重新发起。
3. 请求成功只代表拿到了退款记录，必须继续判断 status。网络超时、5xx 或其他错误可能发生在通道受理之后，不能仅凭错误就换新退款编号。
4. 遇到结果不确定时，先按原 merchant_refund_no 查询。若需要重试申请，保持原业务参数，只刷新外层时间并重新签名。持续未知时请联系平台核对，避免重复退款。

申请成功响应业务对象（处理中示例）

{
  "refund_no": "RF_DEMO_001",
  "merchant_refund_no": "DEMO_REFUND_001",
  "order_no": "ACG_DEMO_ORDER_001",
  "channel_refund_no": "CHANNEL_REFUND_DEMO_001",
  "amount": 400,
  "currency": "CNY",
  "reason": "退回部分商品",
  "status": "processing",
  "trace_id": "TRACE_DEMO_REFUND_001",
  "created_at": "2026-09-30T13:00:00+08:00",
  "updated_at": "2026-09-30T13:00:00+08:00"
}

查询退款 · POST /refund/query

{
  "merchant_refund_no": "DEMO_REFUND_001"
}

查到终结退款时返回已保存结果。对于未终结退款，原插件具备查退能力时会尝试向通道刷新；插件未提供查退能力时只返回当前记录，不保证状态会因此推进。查询超时同样不能当作退款失败。

查询成功响应业务对象（已完成示例）

{
  "refund_no": "RF_DEMO_001",
  "merchant_refund_no": "DEMO_REFUND_001",
  "order_no": "ACG_DEMO_ORDER_001",
  "channel_refund_no": "CHANNEL_REFUND_DEMO_001",
  "amount": 400,
  "currency": "CNY",
  "reason": "退回部分商品",
  "status": "completed",
  "trace_id": "TRACE_DEMO_REFUND_001",
  "created_at": "2026-09-30T13:00:00+08:00",
  "updated_at": "2026-09-30T13:01:00+08:00"
}

退款响应字段

申请与查询返回同一种退款对象，示例中的通道编号和原因属于可选字段。

退款状态与后续动作

部分退款、分账与资金占用

• 部分退款完成后，原支付订单通常仍为 paid；只有累计成功退款金额达到原支付金额才标记 refunded。不能只靠原订单状态判断某一笔部分退款是否完成。
• 已成功及尚未终结的退款都会占用原订单的可退款额度；通道分账也占用同一笔订单金额，已完成的通道分账回退会减少分账净占用。必须确保本次退款不超过剩余可退款余额。
• 已经分出的通道资金如需退给顾客，应先按通道能力完成相应分账回退，再申请退款。用于微信分账代付的订单还受专门限制，完成相应分账回退前不能直接退款。
• 平台商户之间的内部余额分账不同于通道分账，退款时由平台账务处理相应回收；不要把两套分账编号或回退接口混用。退款处理中可能锁定原订单及相关分账资金，未结束前新的退款申请可能被资金冻结限制拦截。

通道分账：支付机构侧资金分配

本节接口实际调用原支付通道的分账能力，将支付机构侧的资金分给该机构的接收账号。它不是平台内商户之间的余额划拨；后者使用商户内部分账。下列均为追加到请求网关的签名 POST 接口，请求示例只展示 biz_content，仍需完整外层参数及 RSA2 签名。

发起通道分账 · POST /split

receivers[] 字段：

当前官方插件的常用 receiver_type：支付宝使用 user_id（支付宝用户 ID）、login_name（登录账号）或 open_id；微信使用 merchant_id（微信商户号，需全称）或 personal_openid。不同插件不可混用类型；开通和绑定关系请在平台通道配置中完成。本接口不接受 rule_id，不能通过请求创建或修改后台分账规则。

{
  "order_no": "ACGP_DEMO_001",
  "merchant_split_no": "CHANNEL_SPLIT_001",
  "amount": 200,
  "currency": "CNY",
  "receivers": [{
    "receiver_id": "ALIPAY_RECEIVER_01",
    "receiver_type": "user_id",
    "account": "2088000000000000",
    "name": "示例接收方",
    "amount": 200,
    "memo": "订单分账",
    "target_type": "merchant"
  }]
}

示例表示向支付宝接收账号分配 2.00 元，所有编号、账号须替换为已开通的真实配置；并非测试收款账号。

金额与状态限制

• 总额不得大于原支付金额，且不得超出通道允许比例：amount × 10000 ≤ 原支付金额 × 通道分账上限 BPS。
• 商户接收项合计不能超过：原支付金额 − 手续费 − 已完成商户内部分账金额 − 退款占用 − 通道分账净占用，低于 0 按 0 处理。回退是否释放占用以已确认成功的回退记录为准。
• 退款及分账处理中、结果未知的金额仍可能占用额度，不可当作失败重新分配；原订单已被微信订单资金代付占用时，不能再发起普通通道分账。
• 通道分账尚未回退的部分会影响原路退款可退金额。需要退款时，先核对剩余可退额，必要时完成分账回退后再发起退款；分账回退本身不会退款给付款人。

查询通道分账 · POST /split/query

{"merchant_split_no":"CHANNEL_SPLIT_001"}

已完成、失败或关闭的记录直接返回本地结果。非终态记录会在原插件支持查分账时尝试向支付机构刷新；不支持查询或该次通道查询失败时，可能仍返回原本地状态。查到记录并不代表已分账成功。

发起 / 查询分账的响应业务字段

以下字段位于已验签响应的 biz_content：

{
  "split_no": "SP_DEMO_001", "merchant_split_no": "CHANNEL_SPLIT_001",
  "order_no": "ACGP_DEMO_001", "amount": 200, "currency": "CNY", "status": "success",
  "receivers": [{
    "receiver_id": "ALIPAY_RECEIVER_01", "receiver_type": "user_id",
    "account": "2088000000000000", "name": "示例接收方", "amount": 200,
    "share_bps": 0, "memo": "订单分账", "target_type": "merchant",
    "merchant_id": "MERCHANT_ID", "status": "success", "success_amount": 200
  }],
  "trace_id": "TRACE_DEMO_001",
  "created_at": "2026-09-30T12:00:00+08:00", "updated_at": "2026-09-30T12:00:01+08:00"
}

通道分账回退 · POST /split/return

从原分账的一名接收方退回指定金额；原分账总体状态必须为 success 或 finished，原订单插件必须实现分账回退。回退仍受支付机构侧规则约束。

{
  "split_no": "SP_DEMO_001", "merchant_return_no": "CHANNEL_RETURN_001",
  "receiver_id": "ALIPAY_RECEIVER_01", "amount": 100, "currency": "CNY", "reason": "退回部分分账"
}

查询通道分账回退 · POST /split/return/query

{"merchant_return_no":"CHANNEL_RETURN_001"}

发起 / 查询回退的响应业务字段

{
  "return_no": "SR_DEMO_001", "merchant_return_no": "CHANNEL_RETURN_001",
  "split_no": "SP_DEMO_001", "order_no": "ACGP_DEMO_001", "receiver_id": "ALIPAY_RECEIVER_01",
  "amount": 100, "currency": "CNY", "reason": "退回部分分账",
  "channel_return_no": "PROVIDER_RETURN_001", "status": "success", "trace_id": "TRACE_DEMO_002",
  "created_at": "2026-09-30T12:01:00+08:00", "updated_at": "2026-09-30T12:01:01+08:00"
}

通道分账状态、重试与结果恢复

creating / processing / pending 为未完成；unknown 为结果不确定；success / finished / completed 为完成类；failed / closed 为失败或关闭。共用资金状态解析器也可能保留插件返回的 refunded 完成类状态；它不是“已退款给顾客”的证据。通道分账回退的前置校验目前只接受原分账状态 success 或 finished。

平台在调用支付机构前保存请求。超时、HTTP 错误或调用失败不保证没有发生资金操作：先用原 merchant_split_no / merchant_return_no 查询。相同商户请求号已存在时不会另起操作；参数不一致会拒绝。分账比较订单、金额、币种及完整接收项（包括顺序）；回退比较原分账、接收方、金额、币种及原因。接收项结果会被插件更新，恢复结果应优先查单，不要靠重新提交或更换请求号判断成功。

商户内部分账：平台账务划拨

将订单扣除手续费后的净收入，按照已审核规则划入平台内其他商户的资金账户；不会调用支付宝、微信等支付机构的分账接口，也不是付款给顾客。以下均为签名 POST，业务参数放在 biz_content。

执行商户内部分账 · POST /merchant-split

不能直接传入 amount、currency、receivers 或任意收款账号。系统按规则计算：net_amount = 原支付金额 − 手续费，每项按净金额乘 share_bps / 10000 取整；总分配额取整后的尾差补给规则最后一项。100 BPS = 1%，总比例须不超过用户组上限，最终金额不得超过订单剩余净资金。

{
  "merchant_order_no": "DEMO_ORDER_001",
  "merchant_split_no": "INTERNAL_SPLIT_001",
  "rule_id": "RULE_DEMO_001"
}

每个支付订单最多执行一次商户内部分账（包括自动分账）。同请求号、同订单返回已有结果，不能借重试替换规则；同请求号用于另一订单会拒绝，同订单换一个请求号也会拒绝。订单已自动分账时，应查询已有分账而非再次申请。极小金额按比例取整为 0 时可能不生成分账记录；必须检查返回的 split_no 和 status，不能只看 HTTP 成功。

查询商户内部分账 · POST /merchant-split/query

{"merchant_split_no":"INTERNAL_SPLIT_001"}

只允许原分账发起商户通过签名接口查询。查询返回平台账务记录，不请求支付机构。

执行 / 查询商户内部分账的响应业务字段

{
  "split_no": "MS_DEMO_001", "merchant_split_no": "INTERNAL_SPLIT_001",
  "rule_id": "RULE_DEMO_001", "order_no": "ACGP_DEMO_001", "source_merchant_id": "MERCHANT_ID",
  "net_amount": 9900, "amount": 1980, "currency": "CNY", "status": "success", "trace_id": "TRACE_DEMO_003",
  "items": [{
    "id": "MSI_DEMO_001", "split_no": "MS_DEMO_001", "receiver_merchant_id": "RECEIVER_MERCHANT_ID",
    "share_bps": 2000, "amount": 1980, "recovered_amount": 0,
    "account_code": "merchant_pending", "status": "pending",
    "available_at": "2026-10-01T12:00:00+08:00",
    "created_at": "2026-09-30T12:00:00+08:00", "updated_at": "2026-09-30T12:00:00+08:00"
  }],
  "created_at": "2026-09-30T12:00:00+08:00", "updated_at": "2026-09-30T12:00:00+08:00"
}

商户内部分账回退 · POST /merchant-split/return

将一名平台接收商户的指定分账金额回退至来源商户账务；原内部商户分账须为 success，接收商户必须存在于该笔分账中。它不发起支付机构分账回退，也不退款给顾客。

币种由原分账确定，不要发送 currency。接收方余额不足时，当前账务实现会将不足部分记入应收账户，不是简单以余额不足拒绝；实际扣回及后续追偿由平台账务处理。

{
  "split_no": "MS_DEMO_001", "merchant_return_no": "INTERNAL_RETURN_001",
  "receiver_merchant_id": "RECEIVER_MERCHANT_ID", "amount": 500, "reason": "回退部分分账"
}

查询商户内部分账回退 · POST /merchant-split/return/query

{"merchant_return_no":"INTERNAL_RETURN_001"}

发起 / 查询内部回退的响应业务字段

{
  "return_no": "MSB_DEMO_001", "merchant_return_no": "INTERNAL_RETURN_001",
  "split_no": "MS_DEMO_001", "order_no": "ACGP_DEMO_001", "merchant_id": "MERCHANT_ID",
  "receiver_merchant_id": "RECEIVER_MERCHANT_ID", "amount": 500, "currency": "CNY",
  "status": "success", "reason": "回退部分分账", "trace_id": "TRACE_DEMO_004",
  "created_at": "2026-09-30T12:01:00+08:00", "updated_at": "2026-09-30T12:01:00+08:00"
}

重试与退款联动

内部划拨在账务事务内完成。响应丢失先按原商户请求号查询，不要换号重复执行。内部回退重复请求会校验原分账、接收商户及金额，匹配时返回原记录；改变原因不会更新原记录。查询仅支持原发起商户，不存在本组接口的专用异步通知。

原订单退款成功后，平台会按退款情况自动追回关联内部商户分账，并更新 recovered_amount；人工回退也会累计到该字段，不能再次回退已追回部分。不要把内部商户分账回退误当作顾客退款成功，更不能用通道分账号调用本组接口。

商户代付

代付从商户可用余额预留本金与手续费，由已开通的代付通道向收款账户转账；不是支付订单退款，也不是商户直接调用支付机构的接口。以下三个接口均使用商户 RSA2 签名信封，示例仅展示 biz_content。

创建代付 · POST /transfer

{
  "request_no": "DEMO_TRANSFER_001",
  "method": "alipay_account",
  "recipient_account": "payee@example.com",
  "recipient_name": "张三",
  "amount": 100,
  "title": "商户结算",
  "remark": "示例代付"
}

代付币种固定 CNY，通道由平台选择。请通过 /transfer/query 查询原代付单，确认最终结果。

审核、限额与资金

• 人工审核创建后为 status=pending_review、review_status=pending；审核通过后才提交通道。自动模式为 review_mode=automatic，创建时即尝试提交。
• 手续费由平台用户组配置计算：固定费加比例费，比例部分向上取整到分，再应用最低 / 最高手续费。以响应 fee_amount 为准，不在请求里自行指定。
• 每日额度按服务器所在时区的当天、同商户记录计算；失败、拒绝和已撤销记录不占该统计，待审核、处理中、待确认、未知及成功记录计入。
• 本金与手续费在创建时预留；成功后结算，失败、审核拒绝或确认撤销后释放。unknown 不能视为失败或重新打款依据。

幂等与超时处理

同一商户重复 request_no 会返回已存在的代付单，不会修改旧单，也不会重新提交；当前实现不比较重试时的账号、金额等新参数。因此必须由商户固定请求号与原业务的对应关系，核对返回数据，严禁将旧请求号用于另一笔转账。命中原单前仍会校验当前平台、商户及用户组权限。

提交超时、接口报错或结果未知时，代付单和资金预留可能已经建立。先用原 request_no 查询，再依原单状态处理；不要更换请求号再创建。重试签名信封须更新时间并重新签名。人工审核期间无需重复提交代付。

查询代付 · POST /transfer/query

{"request_no":"DEMO_TRANSFER_001"}

至少填写一项，建议只传其中一个。两项同时提供时以 transfer_no 为准，当前实现不校验 request_no 是否与其一致。待审核单和已终结单直接返回平台记录；其他状态会尝试查询通道，微信订单分账代付会查询或推进其来源订单的处理。查询失败可能将原单记录为 unknown，应继续核查原单。

撤销代付 · POST /transfer/cancel

{"transfer_no":"TF_DEMO_001"}

请求字段、类型、二选一要求与 /transfer/query 相同。返回同一代付对象。只有实际返回 status=cancelled 才能确认已撤销，接口调用成功本身不代表撤销成功。

• pending_review 可在平台直接撤销并释放预留资金。
• 已终结的 success、failed、rejected、cancelled 原样返回；成功代付不能借此撤回。
• 进入提交阶段后取决于原通道是否实现撤销；不支持时必须查询原结果。微信订单分账代付提交后不支持撤销，只能查单确认。
• 通道撤销报错时可能记录为 unknown，不能直接按已撤销处理，也不能立即重新转账。

代付响应对象

上述三个接口均返回以下结构。先验证外层签名及 code，再核对业务对象；示例为等待人工审核的真实响应结构，编号、金额和时间仅用于说明：

{
  "trace_id": "TRACE_ID",
  "transfer_no": "TF_DEMO_001",
  "request_no": "DEMO_TRANSFER_001",
  "method": "alipay_account",
  "recipient_account_masked": "pa************com",
  "recipient_name_masked": "张*",
  "amount": 100,
  "fee_amount": 0,
  "currency": "CNY",
  "title": "商户结算",
  "remark": "示例代付",
  "status": "pending_review",
  "review_mode": "manual",
  "review_status": "pending",
  "created_at": "2026-09-30T10:00:00+08:00",
  "updated_at": "2026-09-30T10:00:00+08:00",
  "submitted_at": "0001-01-01T00:00:00Z",
  "paid_at": "0001-01-01T00:00:00Z"
}

选择收银台支付方式

发起会话支付 · POST /cashier/pay

这是商户服务端主动为已有收银台会话选择支付方式、创建支付订单的签名接口，适用于自有付款方式选择页面。直接引导用户访问 cashier_url 的普通接入，不必再调用本接口；平台收银台会完成选择。发起支付不表示付款成功。

{
  "session_no": "SESSION_NO_FROM_RESPONSE",
  "pay_type": "alipay",
  "pay_mode": "native",
  "client_ip": "203.0.113.10"
}

金额、币种、商户订单号、标题、通知地址和回跳地址继承原会话，不能通过本接口修改。支付订单仅使用会话剩余有效期，不会重新获得完整有效期。商户、码牌权限及相关通道能力仍须有效。

返回业务对象

返回支付订单对象，与 /pay、/query 同结构，不是收银台会话对象。示例展示成功发起、尚未支付的响应：

{
  "order_no": "ACGP_DEMO_001",
  "merchant_order_no": "DEMO_ORDER_001",
  "pay_type": "alipay",
  "pay_mode": "native",
  "subject": "示例商品",
  "amount": 100,
  "currency": "CNY",
  "fee_amount": 0,
  "status": "paying",
  "pay_info": "https://pay.example.com/DEMO_ONLY",
  "pay_info_type": "qr",
  "trace_id": "TRACE_ID",
  "expired_at": "2026-09-30T10:10:00+08:00",
  "paid_at": "0001-01-01T00:00:00Z",
  "created_at": "2026-09-30T10:00:00+08:00",
  "updated_at": "2026-09-30T10:00:00+08:00"
}

响应字段：order_no、merchant_order_no、pay_type、pay_mode、subject、currency、status、trace_id 为字符串；amount、fee_amount 为整数分；expired_at、created_at、updated_at、paid_at 为 RFC3339 时间。可选字符串为 channel_order_no、description、pay_info、pay_info_type。未付款时 paid_at 可为零时间；过期或不可用的表单支付信息可能被隐藏。付款入口处理和状态说明见直接下单、查询订单。

支付宝小程序 JSAPI

小程序下单 · POST /alipay/mini/create

商户服务端使用平台签名信封调用本接口。小程序先调用 my.getAuthCode({ scopes: 'auth_base' })，将 authCode 交给自己的商户服务端。平台在所选支付通道的小程序 AppID 下兑换授权码，使用 JSAPI_PAY 创建交易，兼容新版 OpenID 和旧版 UID；通道 AppID 必须与客户端小程序一致。小程序支付与支付宝内网页的 jspay 是独立场景。

{"merchant_order_no":"MINI_ORDER_001","subject":"小程序商品","amount":100,"currency":"CNY","expire_seconds":600,"auth_code":"AUTH_CODE_FROM_MY_GETAUTHCODE","mini_app_id":"YOUR_ALIPAY_MINI_APP_ID","notify_url":"https://merchant.example.com/notify"}

返回与 /pay 相同的签名订单业务对象，其中 pay_mode=miniapp、pay_info_type=mini_program，pay_info 与 channel_order_no 是支付宝交易号。商户服务端验平台签名后把交易号交给小程序，调用 my.tradePay({ tradeNO: tradeNo })。私钥、平台签名和上游授权凭据只能由服务端保管。客户端 success 或 resultCode=9000 不能直接交付，最终以平台支付成功通知或 /query 的 paid 为准。

支付宝资金预授权

下列接口均由商户服务端通过签名网关调用，金额均为整数分。需开通支付宝线上资金预授权产品，并使用支持该能力的支付宝官方插件及已授权通道。冻结、解冻保存为独立预授权记录，冻结成功不增加商户余额；只有扣款经支付宝签名通知或交易查询确认付款，才生成正式支付账务。

生成冻结授权 · POST /preauthorization/freeze

{"merchant_authorization_no":"DEPOSIT_001","channel_code":"ALIPAY_CHANNEL","subject":"服务押金","amount":10000,"currency":"CNY","pay_mode":"miniapp","expire_seconds":600,"notify_url":"https://merchant.example.com/payment-notify"}

返回预授权对象：authorization_no、merchant_authorization_no、merchant_id、app_id、plugin_code、plugin_version、channel_code、auth_no、subject、currency、status、payer_id、payer_id_type、order_string 为字符串（未获得的可选字段可能缺省）；amount、version 为整数；expires_at、created_at、updated_at 为 RFC3339 时间，operations 为操作流水对象。每笔流水含 request_no、merchant_request_no、kind、status、order_no、channel_operation_id、reason、error、created_at、updated_at，金额字段 amount 为整数分，complete 为布尔值。返回的 channel_remaining_amount 为支付宝确认的剩余额度（可缺省），available_amount 为扣除处理中操作占用后的可操作额度。

首次状态为 pending，order_string 是签名后的冻结参数串。支付宝小程序调用 my.tradePay({ orderStr: order_string })，APP 使用支付宝 SDK 的订单字符串入口。客户端结果仅触发查状态。冻结经官方通知或查询确认后状态转为 authorized，得到 auth_no。支付宝冻结回调由平台生成地址、验签并核对通道、AppID、冻结号、操作流水与金额；商户使用下方接口查询结果。

查询预授权与操作 · POST /preauthorization/query

{"authorization_no":"AUTHORIZATION_NO","merchant_request_no":"CAPTURE_REQUEST_001"}

authorization_no 与 merchant_authorization_no 为可选 string，至少提供一个；平台编号优先且只能查询当前签名商户的记录。merchant_request_no 为可选 string，可限定查询某个扣款或解冻流水；省略时同步所有操作。响应为同一个预授权对象，操作 status 为 preparing、processing、success 或 failed；预授权 status 为 pending、authorized、completed、released 或 failed。preparing 表示扣款已预留额度但尚未提交通道，可用同请求编号恢复；processing 表示已进入提交阶段，只能查原流水。查询扣款时同步其正式支付订单，只有已核实的 paid 状态才入账。现有支付恢复任务会定时查询原冻结、解冻及扣款流水；支付宝系统到期或账户侧解冻的签名通知只能降低剩余额度，不能将旧通知恢复为可扣款额度。

预授权扣款 · POST /preauthorization/capture

{"authorization_no":"AUTHORIZATION_NO","merchant_request_no":"CAPTURE_REQUEST_001","amount":3000,"complete":false}

使用与查询相同的授权编号字段；merchant_request_no 为必填 string，1 至 64 字符，amount 为必填正整数分，不能超过可操作额度；complete 为可选 boolean，默认 false。false 对应 NOT_COMPLETE，可在授权额度内多次扣款；true 对应 COMPLETE，成功后由支付宝解冻剩余资金并完成该授权。响应是同一预授权对象，其对应流水的 order_no 可用于标准 /query、退款和支付通知核对，平台生成的商户支付订单号就是该 order_no。

同流水、同金额和 complete 重复提交返回原流水；若处于明确尚未提交的 preparing，会先恢复订单落盘再提交一次，变更参数被拒绝。上游接口返回 10000 仍为 processing，不能视为付款成功。超时或返回结果未知时占用额度继续保留，使用原 merchant_request_no 查询；平台不会因重试重新发扣款，也不能另换流水重复扣款。

解冻未消费授权 · POST /preauthorization/unfreeze

{"authorization_no":"AUTHORIZATION_NO","merchant_request_no":"UNFREEZE_REQUEST_001","amount":7000,"reason":"服务已结束，返还剩余押金"}

授权编号字段与查询相同；merchant_request_no 为必填 string，1 至 64 字符，amount 为必填正整数分，reason 为必填 string，2 至 255 字符。解冻不接受 complete=true；部分解冻仅消耗该次金额。解冻金额须不超过扣除已扣款、已解冻和处理中操作后的可操作额度。返回同一对象与解冻操作状态。解冻不生成退款、不增加商户余额；扣款后的已支付资金应通过标准退款接口处理。解冻结果未知时保留占用，按原编号查询。

支付结果通知

支付成功后，平台以 POST application/json 请求商户的 notify_url。这是平台主动通知商户，不是需要商户调用的平台接口。

通知沿用平台签名响应信封，外层 code=0，业务对象包括：

{
  "notify_id": "PAY_PLATFORM_ORDER_NO_SUCCESS",
  "notify_type": "payment.success",
  "order_no": "PLATFORM_ORDER_NO",
  "merchant_order_no": "DEMO_ORDER_002",
  "channel_order_no": "CHANNEL_ORDER_NO",
  "pay_type": "alipay",
  "pay_mode": "native",
  "subject": "示例商品",
  "amount": 100,
  "currency": "CNY",
  "fee_amount": 0,
  "status": "paid",
  "paid_at": "2026-01-01T00:00:00Z",
  "trace_id": "TRACE_ID"
}

1. 保留原始通知 JSON，使用可信平台公钥验签；核对外层 AppID、版本、算法及事件类型。
2. 核对商户订单号、平台订单号、金额、币种与支付方式，确认 notify_type=payment.success 且 status=paid。
3. 在本地事务中更新订单并执行幂等交付，用 notify_id 或平台订单号与事件建立唯一约束。
4. 本地事务成功后，返回 HTTP 2xx，正文为纯文本 success；已处理的重复通知也返回 success。

金额与手续费均为整数分。不要用手续费倒推或替代应付金额。验签失败、金额不符或本地处理失败时，不返回成功确认。

当前公开 HTTP 业务通知为 payment.success。退款、通道分账及回退、商户内部分账、代付没有本页以外的专用商户 HTTP 通知协议，请使用相应查询接口核对结果；不要等待不存在的事件，或将站内消息当作验签后的资金结果。

支付成功通知可携带与查单一致的 payer_id、payer_id_type、payer_scope、payer_id_source，均属于签名 biz_content。易支付对接插件把已核实付款账号映射为 buyer；无身份时保持 null。管理员手动回调会重新读取当前订单并签名，notify_id 保持不变，商户仍须按订单和事件幂等处理。删除回调历史只隐藏已结束记录，不删除订单、账务或原通知幂等任务；执行中或等待重试的记录不可删除。

错误处理与排查

先看 HTTP 状态，再判断签名响应的 code、msg 和业务 status。下表为常见 HTTP 分类；中间件、代理可能返回非签名错误，客户端不能只按固定中文报错文本分支。

求助时提供脱敏订单号、请求时间和 trace_id，不要提供私钥、完整签名请求或付款链接。