接口目录
平台公共支付服务 · 设计参考
| 编号 | 接口名称 | 易宝同款路径 | 方法 | 阶段 | 实现批次 | 说明 |
|---|---|---|---|---|---|---|
| A1 | 付款码收款 | /rest/v1.0/aggpay/pay | POST | 第一阶段 | P2 | 顾客出示付款码,收银台扫码收款。 |
| A2 | 本单二维码 | /rest/v1.0/aggpay/pay-link | POST | 第一阶段 | P3 | 为当前账单生成二维码,让顾客扫码付款;生成码不代表收到钱。 |
| A3 | 查收款订单 | /rest/v1.0/trade/order/query | GET | 第一阶段 | P2 | 查询原收款订单的可信渠道结果,供收银台核实是否到账。 |
| A4 | 关闭订单 | /rest/v1.0/trade/order/close | POST | 第一阶段 | P5 | 请求关闭原订单,再查原单确认最终结果,不能把关单受理当未支付。 |
| A5 | 申请退款 | /rest/v1.0/trade/refund | POST | 第一阶段 | P4 | 对已确认成功的原收款申请原路退款。 |
| A6 | 查退款 | /rest/v1.0/trade/refund/query | GET | 第一阶段 | P4 | 查询同一退款请求的渠道处理结果。 |
| B1 | 支付结果通知 | /api/v1/notify/yeepay | POST | 第一阶段 | —(已有,不在新能力批次中改) | 易宝把支付结果通知我们;我们核对无误并存好以后,才回复易宝收到。 |
| B2 | 退款结果通知 | /api/v1/notify/yeepay/refund | POST | 第一阶段 | P4 | 易宝把退款结果通知我们,我们核对并保存,再更新这笔退款和还能退多少钱。 |
| C1 | 第二跳推送 | 第一阶段 | P7 | 把已确认的收款或退款结果签名推送到调用方登记地址。 | ||
| C2 | 待收银员处理 | /api/v1/collections/pending | POST | 第一阶段 | P7 | 列出需要收银员处理的晚到成功、两笔都成功及待退款记录。 |
| C3 | 处理回执 | /api/v1/collections/pending/handle | POST | 第一阶段 | P7 | 记录收银员选择计入本单还是原路退款;选择本身不是退款成功。 |
| C4 | 账单收款事实 | /api/v1/collections/facts | POST | 第一阶段 | P7 | 查看一张账单的全部收款尝试、已确认金额与退款进度。 |
| C5 | 内部日志查询 | /api/v1/internal/exchange-logs | POST | 第一阶段 | P1b(暂定,独立PR紧跟P1) | 按单号查这笔单和易宝之间来回发过的全部数据(敏感信息已打码),给验收和排查问题用,收银台不能调。 |
| D1 | 存活检查 | /up | GET | 第一阶段 | —(已有,不在新能力批次中改) | 供监控判断应用是否已经启动,不证明依赖可用。 |
| D2 | 就绪检查 | /ready | GET | 第一阶段 | P6 | 供负载均衡和监控检查依赖、配置及后台任务是否就绪。 |
| E1 | 旧付款码接口 | /api/v1/payments/auth-code | POST | 旧接口并行期 | P1(拒绝带 query 的请求) | 是否改动仍待产品负责人决定 |
| E2 | 旧查询接口 | /api/v1/payments/query | POST | 旧接口并行期 | P1(拒绝带 query 的请求) | 是否改动仍待产品负责人决定 |
支付服务平台共用一套,各品牌(含私有化品牌)作为接入应用调用;签名见 v2 规则。
第二阶段接口目录
支付告警设置 · get / update / history(历史接口待合并)
以下均为后续阶段。字段来自批准设计稿,未核对的易宝字段仍标未核对,不生成真实请求。
收款路由 · POST /api/v1/collections/route
8.2 加一个收款路由接口(已定,11/12 09:20)
POST /api/v1/collections/route(本服务自己的 JSON 接口,授权范围 payments)。下单前先问一次“这笔用哪个商户号收”,再照一期稿的易宝同款接口下单。易宝同款接口保持不变,一期稿 Q3 也不用动。
| 入参 | 说明 |
|---|---|
| store_ref | 门店。不传品牌:品牌由本服务按 store_ref 从目录里查出来(见下面规则 8) |
| order_id | 这次收款要用的 orderId(账单号_序号,一期稿第 7 节) |
| order_kind | consumption(消费)/ stored_value_topup(储值) |
| pay_way | auth_code(付款码)/ pay_link(本单二维码)/ wechat_official_account / wechat_mini_program / alipay_mini_program / alipay_h5 |
| amount_fen | 金额(分) |
| collect_via | store(默认)/ coach(教练订单码:只收消费;可以配本单二维码和四种预下单方式,不能配付款码) |
| coach_ref | collect_via=coach 时必填 |
| biz_no | SaaS 单号,选填,用于展示和对账 |
| 出参 | 说明 |
|---|---|
| merchant_no、parent_merchant_no | 这一笔下单要用的收款商编和发起方商编 |
| app_id | 预下单的几种方式才有:这个收款商编登记的、已生效的 appid;调用方要用它去换 openId |
| mode | direct(门店直收)/ pool(收款池)/ coach(教练公司) |
| scheme_version | 用的资金方案版本,直收时为空 |
| terminal_ids | 付款码才有:这个收款商编登记的终端号。下单的 terminalId 要从里面取——收银台的同一台设备轮到不同的收款商户号时,要带的终端号可能不一样(问题 16) |
| route_expires_at | 这条路由保留到什么时候 |
规则:
1. 门店没有生效的资金方案:返回门店直收号,mode=direct,不占额度(r10 已定规则 11)。
2. 有生效方案:消费走消费池、储值走储值池,按 r10 GPAY-05 第 2—5、12、14 条轮流(游标按“门店×池子”加锁;额度按“商户号×业务类型×自然月”;额度不够本次跳过并本月退出;预下单只在这种方式 appid 已生效的成员之间轮)。这笔金额记进选中成员“进行中”的占用。
3. 教练订单码:用这位教练的教练公司商户号收整单,不轮流、不限额,只收消费(r10 GPAY-05 第 8 条)。
4. 同一个“应用+门店+order_id”重复调用,返回第一次的结果;内容不同 409 IDEMPOTENCY_CONFLICT。
5. 到 route_expires_at 还没用这个 orderId 下单的,路由作废、占用释放。默认付款码和二维码 2 分钟,预下单 10 分钟(留出换 openId 的时间),可配。下单以后占用跟着收款单走:成功计入本月已收(退款不回补),失败或关闭释放。
6. 错误:池里没有可用成员 503 POOL_NOT_READY(预下单时没有 appid 已生效的成员,details.reason=appid),并推 pool.not_ready;教练没有启用中的商户号 422 PAYEE_NOT_READY;教练订单码收储值 422 ORDER_KIND_NOT_ALLOWED;直收号或教练公司没配好这种预下单方式 503 CHANNEL_NOT_CONFIGURED(details.reason=appid)。
7. 支付失败不自动换商户号重试:收银员重新发起是新的 orderId,重新路由(r10 GPAY-05 第 6 条)。
8. 授权(复审 P3-1,Lihao 11/12 提):入参没有 brand_ref。服务先按 store_ref 查出这家门店属于哪个品牌,再核对这个应用对“这个品牌的这家门店”有 payments 授权。门店不存在,或者应用没有这家门店的授权,一律回 403 SCOPE_DENIED,返回内容完全一样,不区分是哪一种,免得被拿来试探别家的门店号。这要求 store_ref 在目录里只对应一个品牌;万一登记重复,同样回 403,就绪检查会报出来(第 15.3 节)。
公众号、小程序、支付宝预下单 · POST /rest/v1.0/aggpay/pre-pay
12. 公众号、小程序、支付宝预下单
12.1 接口
易宝同款:POST /rest/v1.0/aggpay/pre-pay,form,签名 v2,规则和一期稿第 3.2 节的公共请求规则完全一样(字段照易宝、金额是元、白名单外的字段拒绝、返回易宝的业务结果对象)。r10 GPAY-07 设计的 /api/v1/payments/pre-pay(JSON)不做。
| pay_way(路由接口里的叫法) | 易宝参数 | 要开通的产品(线下办) | 返回的 prePayTn |
|---|---|---|---|
| 微信公众号 wechat_official_account | payWay=WECHAT_OFFIACCOUNT、channel=WECHAT、userId=openId | WECHAT_OFFIACCOUNT_WECHAT_OFFLINE | JSON,前端解析后调微信 JSAPI |
| 微信小程序 wechat_mini_program | payWay=MINI_PROGRAM、channel=WECHAT、appId、userId=openId | MINI_PROGRAM_WECHAT_OFFLINE | JSON,前端解析后调小程序支付 |
| 支付宝小程序 alipay_mini_program | payWay=MINI_PROGRAM、channel=ALIPAY、userId=支付宝 userId | MINI_PROGRAM_ALIPAY_OFFLINE | 订单号,前端当 tradeNO 传 |
| 支付宝 H5 alipay_h5 | payWay=USER_SCAN、channel=ALIPAY、scene=OFFLINE | USER_SCAN_ALIPAY_OFFLINE | 链接,H5 页面重定向;没装支付宝时用返回里的兜底链接 |
(出处:Skill《微信内 H5+公众号支付》《小程序支付》《浏览器 H5 支付》《prePayTn 唤起方式速查》。)
12.2 请求字段
在线文档的字段表这次没取到,下表是本服务要用到的字段和规则;开发当天按官方字段表补全“拒绝”一栏,变化写进 PR。
| 字段 | 第二阶段 | 规则 |
|---|---|---|
| parentMerchantNo | 可选,服务补 | 同付款码 |
| merchantNo | 必填 | 资金方案已生效的门店,必须是路由给的那个号(第 8.3 节) |
| orderId | 必填 | 同付款码的格式(账单号_序号) |
| orderAmount、goodsName | 必填 | 同付款码 |
| expiredTime | 可选,服务补 | 不传补“现在+15 分钟”;传了必须在 1—15 分钟之内(和付款码一致;第 18 节第 16 项) |
| notifyUrl、memo | 可选 | 同付款码;notifyUrl 只用于第二跳 |
| fundProcessType | 可选,只允许 REAL_TIME | 同付款码 |
| payWay、channel | 必填 | 只允许上表四种组合,别的组合 422 |
| scene | 必填,只允许 OFFLINE | 按线下产品开通;线上场景不在范围 |
| appId | 微信两种必填 | 必须等于路由返回的 app_id(这个收款商编登记的、已生效的 appid),不一致 422。支付宝两种要不要传未核对 |
| userId | 公众号、两种小程序必填;支付宝 H5 不传 | openId 或支付宝 userId,由调用方自己换好,本服务不做微信、支付宝登录。只在本次请求的内存和出站报文里,不落库、不进日志;幂等比对用带密钥的摘要 |
| userIp | 按官方字段表(未核对;付款码是必填) | 调用方看到的真实用户 IP |
| csUrl | 拒绝 | 调用方不能传;资金方案已生效时由本服务补(第 5.4 节) |
| 分账、营销、补贴、记账簿、限制支付方式等其余官方字段 | 拒绝 | 422 VALIDATION_FAILED,写法沿用一期(details.<字段名>=["unsupported_in_phase1"],取值名不另起,调用方少认一种) |
12.3 规则
1. 路由、每笔转入、同账单进行中保护、已付保护、结果不明只查原单,都和本单二维码一样(r10 GPAY-07 第 1 条)。换一种方式或换新,由调用方先关单、再用新的 orderId 下单,本服务不替它关。
2. 返回:易宝预下单的业务结果对象原样返回,prePayTn 不解析、不改;四种方式的类型不同(上表),前端各按各的用。返回码成功只代表预支付单建好了,不代表收到钱;前端回调也不算结果,终态只认通知和查单(GPAY07-04)。返回码怎么分“明确未受理”和“结果不明”,按官方错误码表核对后写进 PR;没列进“明确未受理”的一律算结果不明。
3. 日志:prePayTn 进报文记录前整体换成“类型+长度+摘要”——微信两种的 prePayTn 里带渠道的支付签名(paySign),按一期稿“签名不记”处理。请求里的 userId 按付款人字段删掉。
4. appid:只登记在实际收钱的商户号上(第 4.2 节)。池里没有这种方式 appid 已生效的成员、教练公司或直收号没配好,在路由那一步就报错(第 8.2 节),不会走到下单。
5. 结果通知还是 trade.pay-result,走一期的通知入口;payment.succeeded 等事件推给发起的应用。
6. 顾客端没有收银账单的单(例:自己在手机上充储值)orderId 的“账单号”用什么,由调用方定,只要满足格式;本服务不另起编号规则(第 18 节第 14 项)。
12.4 不做
教练保证金线上缴纳(order_kind=deposit,后期 H62);微信浏览器 H5(经小程序中间页)、APP 支付、银联;线上场景(scene=ONLINE);易宝的 appid 配置接口(只登记进度)。
接口分类与签名
13.1 三类接口和签名
| 类 | 路径 | 格式 | 谁调 | 授权范围 |
|---|---|---|---|---|
| 易宝同款 | /rest/v1.0/…:一期 6 个+预下单 | form / 查询串,签名 v2 | 收银后端、顾客端 | payments |
| 收款路由 | POST /api/v1/collections/route | JSON | 同上 | payments |
| 资金类 | POST /api/v1/fund/…、/pools/…、/schemes/…、/merchants/… | JSON | 品牌总部 | fund、scheme_read、pool_params、deposit |
| 管理类 | POST /api/v1/admin/… | JSON | 平台运营 | platform_admin |
| 一期内部接口 | 待处理、账单事实、报文查询 | JSON | 收银后端、验收 | 一期稿第 12、13.4 节 |
- 外层、字段命名沿用 r10 契约:全部 POST;成功 {"data":…,"meta":{"apiVersion":"v1"}},失败是一期稿第 5 节的 {"error":{code,message,details}};snake_case;金额整数分;Cache-Control: no-store。
- 幂等:每个写接口带调用方的业务单号(*_ref 或 request_ref),在本应用内唯一;同号同内容返回第一次的结果,同号不同内容 409 IDEMPOTENCY_CONFLICT(r10 已定规则 2)。
- 授权:每个请求按“应用 → 品牌 → 门店 → 商户号”核对(一期稿第 2 节);资金类按 brand_ref;收款路由的入参只有 store_ref,品牌由服务按门店查出,再按“品牌+门店”核对(第 8.2 节规则 8)。查询只能看到本应用授权范围内的单。
- 限流按应用。管理类接口和报文查询只对平台私网开放。
JSON 接口的签名(按建议做;Lihao 有异议再改):r10 写的是沿用 v1(5 行待签串)。新加的 JSON 接口都用签名 v2 的 JSON 写法:
- 待签串就是一期稿第 4.3 节的 8 行,算法行、时间戳、nonce 的规则不变;第 4 行(查询串)恒为空,带查询串直接拒绝;第 5 行 Content-Type 必须正好是 application/json;第 6 行是请求体原始字节的摘要。
- 判断顺序、401 的 details.reason 取值、WWW-Authenticate 头都和第 4.3 节一样;没有“规范性”那一步(它管的是表单编码)。正文不是合法的 JSON 对象,在验签通过以后回 422。业务只读这份 JSON,不合并查询串和表单。
- 每条路由只认一种格式:易宝同款只认 form,JSON 接口只认 JSON。
- 好处:新接口不再依赖 v1,旧付款码接口下线时 v1 可以一起下线(一期稿第 4.1 节说明了 v1 现在下不掉的原因);401 的原因也和易宝同款接口一个口径。代价:品牌总部 SaaS 的签名要按 v2 写一遍。
- 一期稿第 12 节的内部接口(P7,还没实现)建议同样改用它;P1b 已经实现的报文查询接口可以两种都认。产品负责人 11/12 09:20 同意按这个做,Lihao 有异议再改(第 18 节第 2 项)。
第二跳推送 · SP-PUSH-2
13.5 事件(第二跳推送)
在一期稿第 11.2 节的推送 v2 上加资金类事件。请求头、签名(SP-PUSH-2 的 9 行)、去重和版本规则、投递和重试、防 SSRF 的规则都不变。
对象。一期的对象身份是“对象类型+商户号+对象号”。资金类对象的编号在本服务内唯一,不靠商户号区分,签名里“商户号”那一行固定写 -(X-SP-Merchant-No: -;建议,不用空串是因为有的 HTTP 组件会丢掉空的头)。
| object_type | object_ref | 事件 |
|---|---|---|
| payment(一期) | orderId | payment.succeeded、failed、closed |
| refund(一期) | refundRequestId | 一期的 refund.succeeded、failed;新增 refund.fund_return_stuck、refund.fund_returned_to_hq |
| fund_order | fund_order_ref | store_in.succeeded、failed;sweep.succeeded、failed(含公域归集);x3_topup.recorded;commission.succeeded、failed;transfer.succeeded、failed;withdrawal.paid、reversed;fund_order.failed、review_required |
| payout | payout_ref | payout.step_succeeded、step_failed、line_cancelled、completed |
| deposit | 转入的 transfer_ref 或退还的 refund_ref | deposit.paid、refunded、refund_attention |
| scheme | scheme_ref | scheme.published、withdrawn、effective、effective_failed |
| pool、balance_check、recon | 每次发生一个新编号 | pool.member_exited、member_returned、not_ready;balance_check.diff_found;recon.diff_found |
- 相对 r10 GPAY-14:split.* 改名 store_in.*,别的事件名不变。
- 版本:有状态的对象每次状态变化版本加 1,接收方只认更大的版本;refund 的资金退回状态变化也加版本。最后一行的三种不是某个对象的状态变化,每次是一个新对象,版本固定 1。
- 正文:本服务自己的 JSON(snake_case、整数分),内容和对应查询接口里这个对象的出参一致;不是易宝报文。发给平台运营应用的事件不带余额。
- 推给谁照 r10 GPAY-14 第 2 条,把“本品牌的 hq 应用”读成“类型是品牌总部、对这个品牌有授权的应用”(可以不止一个,每个应用各一条事件、各用各的推送密钥):收款、退款结果给发起的应用;资金退回类给发起退款的应用和本品牌总部;自动发起的资金单、收款池、余额核对给本品牌总部;总部发起的给发起的应用;资金方案给本品牌总部和平台运营;对账差错给平台运营。
- 推到哪:收款、退款的事件用下单请求里的 notifyUrl(一期)。资金类事件没有对应的请求,推到应用登记的默认事件地址——推送地址白名单里标成默认的那一条(第 14.1 节);没登记默认地址的应用不推,靠查询兜底。
- fund_order.review_required 是待核提醒,不是结果:照 M10-R98 推给本品牌总部。一期“结果不明、待核不推”(Q16)说的是不给收银后端推收款的不明结果,两件事不冲突。
- 兜底:推送投递失败的,品牌总部每天用 fund/orders/list 按更新时间对一遍(r10 GPAY-14 第 5 条)。
资金类接口
13.2 资金类接口
入参、出参照 r10“调用方与支付服务之间的接口”的表,下面只列接口和相对 r10 的改动。
| 接口 | 用途 | 相对 r10 的改动 |
|---|---|---|
| fund/balances、fund/accounts | 余额、账户清单 | 无(第 10.1 节) |
| fund/settings | 退款备付金 | 无 |
| fund/transfers | 人工转账(品牌级) | 无 |
| fund/manual-transfers、/preview | 转账提现 | “余额分账”改“转账”;预览带 transfer_fee_state(未配置 unconfirmed / 不收 none / 按费率 rate,第 4.4 节),收手续费时另带金额 |
| fund/commissions | 每个营业日抽佣 | 营业日按自然日,business_date 要到次日 00:00 才算结束 |
| fund/payouts、/query、/cancel-line | 付款、总部提现、撤销一行 | 两步都是转账 |
| fund/withdrawals/redo | 被银行退回后重新提现 | 无 |
| fund/withdrawal-fee/quote | 易宝提现手续费试算 | 出参加 transfer_fee_state(第 4.4 节) |
| fund/orders/list、/get、/retry | 资金流水、详情、重试 | 类型 split 改 store_in;转入门店的行另给顾客实付 |
| fund/balance-checks/latest、/run | 余额核对 | 无(第 10.2 节) |
| fund/deposits/transfer-in、/refund、/get、/ledger | 保证金 | “余额分账”改“转账” |
| pools/get、/members/update、/changes | 收款池(只读+限额、顺序) | 小版本下一个营业日 00:00 生效 |
| schemes/list、/get、/versions | 资金方案(只读) | 线的 method 取值(第 7.1 节) |
| merchants/options、/withdraw-card | 可选商户号、提现卡 | options 里“待确认”角色的号 selectable=false,原因写明 |
错误码
13.4 错误码
一期稿第 5 节和 r10 契约“错误码”表的码全部沿用,不重抄。改动和新增:
| 错误码 | 状态 | 改动 |
|---|---|---|
| BUSINESS_DATE_NOT_ENDED | 422 | 含义改成“还没到次日 00:00” |
| VALIDATION_FAILED | 422 | 新的 details:merchantNo 取 route_required、route_mismatch、route_expired(第 8.3 节) |
| REFUND_IN_PROGRESS | 409 | 新的 details.stage:fund_return(资金退回中)、dispatch(正在派发,一期的含义)、fund_reverse(原路退失败,正在收回总部)(第 9.7 节) |
| TRANSFER_DIRECTION_NOT_ALLOWED | 422 | 新的 details.reason=initiator_mismatch:两个号的发起方商编不同,暂时不能互转(第 7.2 节第 14 条,问题 3) |
| SCHEME_VALIDATION_FAILED | 422 | 校验条目按第 7.2 节 |
| REVIEW_ACTION_NOT_ALLOWED | 409 | 新增:这张单现在不能用这个人工处理动作(第 14.4 节) |
| UNAUTHENTICATED | 401 | JSON 接口用签名 v2 时,details.reason 同一期稿第 4.3 节 |
管理类接口与页面映射
| 平台页面 | 管理接口组(POST) |
|---|---|
| 接入应用 | POST /api/v1/admin/apps/* |
| 商户档案 | POST /api/v1/admin/merchants/* |
| 通道配置 | POST /api/v1/admin/channel-accounts/list |
| 资金单 | POST /api/v1/admin/fund-orders/* |
| 对账差错 | POST /api/v1/admin/recon-diffs/* · POST /api/v1/admin/recon/rerun |
| 推送记录 | POST /api/v1/admin/deliveries/* |
| 资金方案 | POST /api/v1/admin/schemes/* · POST /api/v1/admin/direct-collect/* |
| 收款池成员 | POST /api/v1/admin/pools/* |
JSON、签名 v2、platform_admin,仅平台私网。接口组内字段按 r10;本原型不补造未列契约。
退款与关单补充规则 · 尚未合并来源
收款尚未确认已付时不能退款:409 PAYMENT_NOT_CONFIRMED,请先查单。全额退款后,同一账单不能再收,请新开一张单。
关单不改收款状态,状态只由查单决定;关单没成功,后台按 5 / 15 / 60 / 300 秒再关,总共最多 5 次。结果不明的前一笔调过关单,且本次查到确实没付,才能收新的一笔。
来源:支付服务 #24(未合并)1dddfa2f5c308cdaf0b84924fff647fec258c09e;#26(未合并)becbbd133fd5e430fbd30ceacbfcb64b02cc9912。
来源:支付服务 #20 · 批准提交 707ca08;只读设计展示,未接通,不代表已实现。