接口文档

可购买的技术服务

接入地址

生产环境 API 根路径：https://api.flowpay.cn。每个应用/站点使用独立的 FlowPay 应用凭据调用接口，凭据只在创建时显示一次。

接口约定

FlowPay 对外只使用 GET 和 POST。路径最多包含一个动态参数；多个资源 标识放在 GET 查询参数或 POST 请求体中，不使用多层嵌套路由。所有请求与 响应 JSON 字段均使用 snake_case，不使用驼峰命名。

创建订单

POST https://api.flowpay.cn/v1/orders，Authorization: Bearer fp_live_... 。应用身份由凭据确定，请勿在请求体中重复提交 application_code。

{
  "out_trade_no": "20260908000123000001",
  "amount_fen": 100,
  "description": "技术服务",
  "channel": "alipay_h5"
}

out_trade_no 支持 1～32 位字母、数字、下划线和连字符；商城应把自身稳定的 支付尝试号原样传入，并在同一次支付重试中复用它。省略时 FlowPay 会按 YYYYMMDDHHMMSS + 6 位秒内原子序列自动生成。响应中的 order.order_no 是 FlowPay 全局唯一 20 位订单号，order.out_trade_no 是商户订单号， order.provider_out_trade_no 是实际提交给支付渠道的请求单号。成功时返回 渠道侧支付参数，金额单位为人民币分。

// 微信 Native
{"client_params":{"code_url":"weixin://wxpay/bizpayurl?..."}}

// 微信 JSAPI
{"client_params":{"app_id":"wx...","time_stamp":"...","nonce_str":"...","package":"prepay_id=...","sign_type":"RSA","pay_sign":"..."}}

// 支付宝 H5：支付宝扫一扫应编码官方跳转辅助链接 alipay_qr_payload；普通浏览器打开 payment_page_url
{"payment_page_url":"https://pay.flowpay.cn/pay/<token>","alipay_qr_payload":"https://render.alipay.com/p/s/i/?scheme=...","client_params":{"payment_page_url":"https://pay.flowpay.cn/pay/<token>","alipay_qr_payload":"https://render.alipay.com/p/s/i/?scheme=..."}}

// 支付宝电脑网站
{"client_params":{"payment_url":"https://openapi.alipay.com/gateway.do?..."}}

支付宝 H5 不直接提供 Native 二维码。FlowPay 会为每笔 H5 订单生成 一次性订单中心地址，并同时返回支付宝官方跳转辅助链接 alipay_qr_payload。支付宝扫一扫应优先将 alipay_qr_payload 转成二维码， 这样会在支付宝内部打开订单中心；普通浏览器则直接打开 payment_page_url。 订单中心展示金额、商品说明和倒计时，用户点击后才进入支付宝 H5；支付结果以 支付宝异步通知为准。

查询订单

GET https://api.flowpay.cn/v1/orders/:out_trade_no，Authorization: Bearer fp_live_...

查询和关单接口直接返回扁平订单对象，不包含创建接口的 order 包装层。状态包括 created、paid、closed、refunded、failed。已支付状态仅在渠道确认后出现， 接口本身不生成资金流水。

查询/关单成功响应（扁平订单对象）
{
  "order_no":"20260925120000123456",
  "out_trade_no":"SF20260924-91A63F37D7C7-1",
  "provider_out_trade_no":"20260925120000123456",
  "amount_fen":24,
  "channel":"alipay_h5",
  "status":"paid",
  "paid_at":"2026-09-25T04:00:00Z",
  "expires_at":"2026-09-25T04:30:00+08:00"
}

错误响应
{"request_id":"req_...","error":{"code":"ORDER_NOT_FOUND","message":"order not found"}}

关单接口会先查询上游并在关单后再次确认。如果发现订单实际已经付款，接口仍返回 HTTP 200，且扁平订单对象的 status 为 paid；商城必须按已付款处理，不能因为用户 点击了取消就覆盖支付成功状态。订单不存在时返回 404 ORDER_NOT_FOUND。

退款

原生 API 支持微信和支付宝的全额或部分退款。退款请求使用应用范围内稳定的 order_no 定位原支付订单，out_refund_no 作为商城退款订单号和幂等键；只有已确认 paid 的订单可以退款，退款金额不能超过剩余可退金额。

POST https://api.flowpay.cn/v1/refunds
Authorization: Bearer fp_live_...
Content-Type: application/json

{
  "order_no":"20261002024344000001",
  "out_refund_no":"RF20261001-ORDER-1",
  "amount_fen":100,
  "reason":"用户申请退款"
}

查询退款：GET https://api.flowpay.cn/v1/refunds/:out_refund_no；按 FlowPay 订单查询： GET https://api.flowpay.cn/v1/refunds?order_no=...。渠道只返回 processing 时， FlowPay 不会提前标记 succeeded；当前通过控制台同步查询推进最终状态。状态变化会以 refund.updated 事件进入原生 JSON/HMAC 回调队列。微信退款结果通知入口为 /v1/wechat/refund-notify；支付宝标准退款接口沿用原支付订单的 notify_url （/v1/alipay/notify）。两者均由 worker 定期查询确认兜底。提交给微信或支付宝的渠道退款请求号是 FlowPay 返回的 refund_no，不能把不同应用可能重复的 out_refund_no 直接当作上游退款号。

退款间隔、单订单次数上限、退款期限和是否串行提交，均由控制台“支付方式 → 应用订单策略”中的退款防护策略管理，不写死在业务代码中。策略值为 0 时表示 FlowPay 不增加本地限制，但微信/支付宝自身规则仍然有效。创建恢复宽限 和对账间隔也由同一策略管理；未知渠道状态进入 abnormal 并继续冻结额度， worker 会自动查询收敛，且已成功退款不会被较旧查询结果回退。

易支付兼容接入

FlowPay 为每个应用生成独立 PID/PKey，下游可以复用主流易支付客户端的 MD5 协议调用。创建接口为 POST https://api.flowpay.cn/mapi.php，提交 pid、type、 out_trade_no、notify_url、name、money、sign_type 和 sign；查单接口为 POST https://api.flowpay.cn/api.php，使用 pid、key、 act=order 和 out_trade_no。out_trade_no 支持 1～32 位字母、数字、 下划线和连字符。

type=wxpay 或 alipay
sign_type=MD5
sign=所有非空参数按字段名排序后直接拼接 PKey 的 MD5（小写）

每个应用都具有独立的 FlowPay 订单有效期，新应用默认为 30 分钟，运营人员可以在控制台按应用调整。下游主动取消时，可向同一 api.php 提交 act=close、pid、key 和 out_trade_no；FlowPay 会先查询官方渠道，确认未支付后再关闭微信或支付宝订单。

wxpay 会返回微信 Native 的 qrcode；alipay 会返回 FlowPay 订单中心的 payurl/qrcode。真实支付仍使用 FlowPay 已配置的官方微信或支付宝连接， 支付完成后 FlowPay 验证平台通知，并在同一数据库事务中更新订单、写入 易支付通知队列，再按下单时的 notify_url 异步回传。notify_url 必须使用 HTTPS，客户端应按 out_trade_no 做幂等。

易支付创建、查单和通知中的 trade_no 是 FlowPay 全局订单号； out_trade_no 始终原样返回下游提交的商户订单号。微信或支付宝自己的交易号 仅用于 FlowPay 对账，不会替代这两个字段。

下游选择 qrcode 模式时调用 mapi.php 并自行展示二维码；选择 popup 模式时打开 submit.php，FlowPay 会统一跳转托管收银台。PC 收银台对微信和支付宝都展示二维码、倒计时和实时状态；支付宝可额外在当前设备继续支付。

支付结果回调

易支付接入方应在每笔签名下单请求中提交自己的 HTTPS notify_url 和可选 return_url。FlowPay 会把两个地址与订单绑定：notify_url 用于服务端支付 结果通知，return_url 只在确认支付成功后提供给托管收银台用于浏览器返回。 不同 PID 对应不同应用，历史订单始终使用创建时保存的地址快照。

使用 FlowPay 原生 Bearer API 时，商户在控制台“开发者”中为应用配置 HTTPS 业务回调地址。微信和支付宝平台通知由 FlowPay 先验签入库，再通过 JSON/HMAC 协议异步投递；支付方式页面中的渠道 notify_url 是微信或支付宝 通知 FlowPay 的入口，不是下游商户回调地址。

每次回调都包含 event_id、event_type、out_trade_no、provider_state 和 status，字段统一使用 snake_case。请求头会带有 X-FlowPay-Event-ID、X-FlowPay-Timestamp 和 X-FlowPay-Signature。签名原文为 timestamp + "." + 请求 JSON，使用 应用回调密钥计算 HMAC-SHA256，格式为 sha256=十六进制摘要。非 2xx 响应会按指数退避自动重试，重复 event_id 必须幂等处理。

易支付和原生 API 通知均使用 PostgreSQL 持久化队列。失败会按 1 分钟、5 分钟、30 分钟、2 小时和 24 小时退避，最多尝试 8 次；易支付接入方应返回 2xx 以及空正文或 success。运营人员可在控制台“开发者”页面查看投递状态， 并将最终失败事件按原始签名快照重新投递。

FlowPay 会按订单创建入口自动选择通知协议：易支付订单只发送签名下单时 保存的 notify_url，原生 Bearer API 订单才使用应用业务回调。同一应用可 同时开放两种入口，但同一笔订单不会重复发送两种协议的通知。

开通与售后

浏览本文档无需登录。开通联调账号请通过首页联系商务，邮件 hello@flowpay.com，QQ 3948661591。

前往开始对接