平台端 / 支付管理 / 接口目录
西安禾斗 · 平台运营

接口目录

平台公共支付服务 · 设计参考

编号接口名称易宝同款路径方法阶段实现批次说明
A1付款码收款/rest/v1.0/aggpay/payPOST第一阶段P2顾客出示付款码,收银台扫码收款。
A2本单二维码/rest/v1.0/aggpay/pay-linkPOST第一阶段P3为当前账单生成二维码,让顾客扫码付款;生成码不代表收到钱。
A3查收款订单/rest/v1.0/trade/order/queryGET第一阶段P2查询原收款订单的可信渠道结果,供收银台核实是否到账。
A4关闭订单/rest/v1.0/trade/order/closePOST第一阶段P5请求关闭原订单,再查原单确认最终结果,不能把关单受理当未支付。
A5申请退款/rest/v1.0/trade/refundPOST第一阶段P4对已确认成功的原收款申请原路退款。
A6查退款/rest/v1.0/trade/refund/queryGET第一阶段P4查询同一退款请求的渠道处理结果。
B1支付结果通知/api/v1/notify/yeepayPOST第一阶段—(已有,不在新能力批次中改)易宝把支付结果通知我们;我们核对无误并存好以后,才回复易宝收到。
B2退款结果通知/api/v1/notify/yeepay/refundPOST第一阶段P4易宝把退款结果通知我们,我们核对并保存,再更新这笔退款和还能退多少钱。
C1第二跳推送第一阶段P7把已确认的收款或退款结果签名推送到调用方登记地址。
C2待收银员处理/api/v1/collections/pendingPOST第一阶段P7列出需要收银员处理的晚到成功、两笔都成功及待退款记录。
C3处理回执/api/v1/collections/pending/handlePOST第一阶段P7记录收银员选择计入本单还是原路退款;选择本身不是退款成功。
C4账单收款事实/api/v1/collections/factsPOST第一阶段P7查看一张账单的全部收款尝试、已确认金额与退款进度。
C5内部日志查询/api/v1/internal/exchange-logsPOST第一阶段P1b(暂定,独立PR紧跟P1)按单号查这笔单和易宝之间来回发过的全部数据(敏感信息已打码),给验收和排查问题用,收银台不能调。
D1存活检查/upGET第一阶段—(已有,不在新能力批次中改)供监控判断应用是否已经启动,不证明依赖可用。
D2就绪检查/readyGET第一阶段P6供负载均衡和监控检查依赖、配置及后台任务是否就绪。
E1旧付款码接口/api/v1/payments/auth-codePOST旧接口并行期P1(拒绝带 query 的请求)是否改动仍待产品负责人决定
E2旧查询接口/api/v1/payments/queryPOST旧接口并行期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_kindconsumption(消费)/ stored_value_topup(储值)
pay_wayauth_code(付款码)/ pay_link(本单二维码)/ wechat_official_account / wechat_mini_program / alipay_mini_program / alipay_h5
amount_fen金额(分)
collect_viastore(默认)/ coach(教练订单码:只收消费;可以配本单二维码和四种预下单方式,不能配付款码)
coach_refcollect_via=coach 时必填
biz_noSaaS 单号,选填,用于展示和对账
出参说明
merchant_no、parent_merchant_no这一笔下单要用的收款商编和发起方商编
app_id预下单的几种方式才有:这个收款商编登记的、已生效的 appid;调用方要用它去换 openId
modedirect(门店直收)/ 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_accountpayWay=WECHAT_OFFIACCOUNT、channel=WECHAT、userId=openIdWECHAT_OFFIACCOUNT_WECHAT_OFFLINEJSON,前端解析后调微信 JSAPI
微信小程序 wechat_mini_programpayWay=MINI_PROGRAM、channel=WECHAT、appId、userId=openIdMINI_PROGRAM_WECHAT_OFFLINEJSON,前端解析后调小程序支付
支付宝小程序 alipay_mini_programpayWay=MINI_PROGRAM、channel=ALIPAY、userId=支付宝 userIdMINI_PROGRAM_ALIPAY_OFFLINE订单号,前端当 tradeNO 传
支付宝 H5 alipay_h5payWay=USER_SCAN、channel=ALIPAY、scene=OFFLINEUSER_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/routeJSON同上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_typeobject_ref事件
payment(一期)orderIdpayment.succeeded、failed、closed
refund(一期)refundRequestId一期的 refund.succeeded、failed;新增 refund.fund_return_stuck、refund.fund_returned_to_hq
fund_orderfund_order_refstore_in.succeeded、failed;sweep.succeeded、failed(含公域归集);x3_topup.recorded;commission.succeeded、failed;transfer.succeeded、failed;withdrawal.paid、reversed;fund_order.failed、review_required
payoutpayout_refpayout.step_succeeded、step_failed、line_cancelled、completed
deposit转入的 transfer_ref 或退还的 refund_refdeposit.paid、refunded、refund_attention
schemescheme_refscheme.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_ENDED422含义改成“还没到次日 00:00”
VALIDATION_FAILED422新的 details:merchantNo 取 route_required、route_mismatch、route_expired(第 8.3 节)
REFUND_IN_PROGRESS409新的 details.stage:fund_return(资金退回中)、dispatch(正在派发,一期的含义)、fund_reverse(原路退失败,正在收回总部)(第 9.7 节)
TRANSFER_DIRECTION_NOT_ALLOWED422新的 details.reason=initiator_mismatch:两个号的发起方商编不同,暂时不能互转(第 7.2 节第 14 条,问题 3)
SCHEME_VALIDATION_FAILED422校验条目按第 7.2 节
REVIEW_ACTION_NOT_ALLOWED409新增:这张单现在不能用这个人工处理动作(第 14.4 节)
UNAUTHENTICATED401JSON 接口用签名 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;只读设计展示,未接通,不代表已实现。