MERCHANT API · PUBLIC DOCUMENTATION

FluxPay 商户 API

面向商户技术团队的完整接入说明。本文档公开访问，无需登录；所有业务请求统一使用 POST application/json。

请求格式JSON

签名算法HMAC-SHA256

金额单位最小货币单位整数

字符编码UTF-8

接入原则

商户只使用 FluxPay 分配的商户号、商户密钥、平台 product_code 和 bank_id。接口不会返回任何上游机构编码、上游订单号或内部路由信息。

公共说明

项目	规则
请求方式	本文档内所有商户接口均为 `POST`，请求头必须包含 `Content-Type: application/json`。
金额	使用最小货币单位整数，建议以字符串传输。例如 VND 100,000 传 `"100000"`，禁止传小数。
商户订单号	`mch_order_no` 在同一商户下唯一，长度不超过 128 个字符。
幂等	相同商户订单号和相同核心参数重复提交会返回原订单，并将 `idempotent_replay` 标记为 `true`；核心参数不同返回 HTTP 409。
代收状态	`UNPAID` 未支付、`PAID` 已支付。
代付状态	`PAYING` 打款中、`SUCCESS` 打款成功、`REJECTED` 已驳回。
时间格式	响应时间使用 RFC 3339，例如 `2026-07-14T10:30:00Z`。

请求认证与签名

认证参数与业务参数放在同一个 JSON 请求体内，每个请求都必须重新生成 nonce 和签名。

公共请求参数

参数	类型	必填	示例	说明
`mch_id`	string	是	1000	平台分配的商户号，同时作为 API 请求身份标识。
`req_time`	string	是	1784000000	Unix 秒或 `yyyyMMddHHmmss`，与平台时间偏差不能超过 5 分钟。
`nonce_str`	string	是	a8f3c91b	本次请求唯一随机字符串。有效期内重复使用会被拒绝。
`sign`	string	是	32a6…	HMAC-SHA256 结果，使用十六进制小写字符串。

签名步骤

排除字段 sign 以及值为空字符串或 null 的字段。
其余标量参数按参数名 ASCII 升序排列。
按 key=value 格式使用 & 连接，值使用实际发送值。
以商户密钥作为 HMAC 密钥，对参数字符串计算 HMAC-SHA256，并转为十六进制小写。

签名原文示例

amount=100000&mch_id=1000&mch_order_no=IN202607140001&nonce_str=a8f3c91b&notify_url=http://merchant.example/callback/payin&payment_method_code=ALL&product_code=1000&req_time=1784000000

伪代码

canonical = sort_and_join_non_empty_fields(request_without_sign)
sign = hex_lowercase(HMAC_SHA256(merchant_secret, canonical))

注意

商户密钥只允许保存在服务端，不得写入网页、App 或客户端日志。更换密钥后应立即更新调用端配置。

创建代收

创建一笔收款订单，返回平台统一收银台和可用的标准化收款数据。

接口用途

商户提交自己的订单号、平台支付产品编码和金额。平台根据 product_code 确定国家、币种和路由，商户不提交 country 或 currency。

请求地址和请求方式

POST/v1/payinsContent-Type: application/json

请求参数

参数	类型	必填	说明
`mch_id`	string	是	商户号。
`mch_order_no`	string	是	商户代收订单号，同一商户下唯一，最长 128 字符。
`product_code`	integer	是	平台支付产品编码，从“支付产品目录”接口获取。
`payment_method_code`	string	否	从目录的 `payment_methods` 选择；省略时仅匹配显式 `ALL` 通用能力。
`amount`	string	是	订单金额，最小货币单位正整数。
`notify_url`	string	否	HTTP 或 HTTPS 公网异步通知地址。
`return_url`	string	否	付款结束后的浏览器跳转地址，必须为 HTTPS 公网地址。
`customer_reference`	string	否	商户侧客户标识，可用于客户跟踪或风控关联。
`collection_card_number`	string	否	指定收款卡号；无指定需求时不要传。
`original_merchant_order_no`	string	否	需要关联原订单时填写原商户订单号。
`kyc_reference`	string	否	商户侧实名或风控校验引用。
`req_time` / `nonce_str` / `sign`	string	是	公共认证参数。

完整 JSON 请求示例

创建代收请求

{
  "mch_id": "1000",
  "mch_order_no": "IN202607140001",
  "product_code": 1000,
  "payment_method_code": "ALL",
  "amount": "100000",
  "notify_url": "http://merchant.example/callback/payin",
  "return_url": "https://merchant.example/pay/result",
  "req_time": "1784000000",
  "nonce_str": "a8f3c91b",
  "sign": "32a6d41f24d933942ef0b92898f93d31e51e3d6ff196d879abc123456789abcd"
}

返回参数

参数	类型	说明
`platform_order_no`	string	FluxPay 平台订单号。
`mch_order_no`	string	商户提交的代收订单号。
`status`	string	`UNPAID` 或 `PAID`。
`currency`	string	产品绑定的三位大写币种。
`amount_minor`	integer	订单金额，最小货币单位整数。
`payment_method_code`	string	订单实际支付方式编码。
`checkout_url`	string	平台统一收银台地址。
`payment_data`	object	标准化收款信息，未取得的字段为 `null`。
`payment_data.payee_name`	string\|null	收款人名称。
`payment_data.payee_account`	string\|null	收款账号或银行卡号。
`payment_data.bank_name`	string\|null	收款银行名称。
`payment_data.pay_amount`	string\|number\|null	本次应付金额。
`payment_data.qr_url`	string\|null	支付二维码图片地址。
`payment_data.qr_text`	string\|null	支付二维码原始文本。
`payment_data.payment_remark`	string\|null	付款备注。
`payment_data.payee_account_id`	string\|null	平台标准化收款账户标识。
`notify_status`	string	异步通知状态。
`idempotent_replay`	boolean	是否为幂等重复提交。
`created_at`	string	订单创建时间。

成功返回示例

HTTP 200

{
  "platform_order_no": "DS000000000001000",
  "mch_order_no": "IN202607140001",
  "status": "UNPAID",
  "currency": "VND",
  "amount_minor": 100000,
  "checkout_url": "https://pay.example.com/checkout/order-reference",
  "payment_data": {
    "payee_name": "NGUYEN VAN A",
    "payee_account": "0123456789",
    "bank_name": "Example Bank",
    "pay_amount": "100000",
    "qr_url": null,
    "qr_text": null,
    "payment_remark": "PAY DS000000000001000",
    "payee_account_id": null
  },
  "notify_status": "NOT_NOTIFIED",
  "idempotent_replay": false,
  "created_at": "2026-07-14T10:30:00Z"
}

失败返回示例

HTTP 400

{"error":"payment product or bank is unavailable"}

注意事项

不要提交 country、currency 或任何第三方产品编码。商户应保存 platform_order_no 与自身订单号的映射，并优先通过查询或回调确认最终支付状态。

创建代付

向银行卡或二维码收款对象发起一笔代付订单。

接口用途

商户提交平台银行或钱包 ID、收款人和金额。平台根据 bank_id 判断国家与币种；银行卡号（钱包目标为绑定手机号）和二维码文本必须严格二选一。

请求地址和请求方式

POST/v1/payoutsContent-Type: application/json

请求参数

参数	类型	必填	说明
`mch_id`	string	是	商户号。
`mch_order_no`	string	是	商户代付订单号，同一商户下唯一。
`amount`	string	是	代付金额，最小货币单位正整数。
`bank_id`	integer	是	平台银行或钱包 ID，从“银行与钱包目录”获取。
`payment_method_code`	string	否	从银行目录的 `payment_methods` 选择；省略时仅匹配显式 `ALL` 通用能力。
`beneficiary_name`	string	是	收款人姓名，最长 160 字符。
`beneficiary_card_number`	string	二选一	银行目标传收款银行卡号；钱包目标传钱包绑定手机号。与 `beneficiary_qr_text` 不能同时提交。
`beneficiary_qr_text`	string	二选一	二维码原始文本，不是图片或 Base64，最长 4096 字符。
`beneficiary_bank_name`	string	否	收款银行名称。
`beneficiary_subbranch`	string	否	收款支行名称。
`notify_url`	string	否	HTTP 或 HTTPS 公网异步通知地址。
`req_time` / `nonce_str` / `sign`	string	是	公共认证参数。

完整 JSON 请求示例

银行卡代付请求

{
  "mch_id": "1000",
  "mch_order_no": "OUT202607140001",
  "amount": "250000",
  "bank_id": 7,
  "payment_method_code": "ALL",
  "beneficiary_name": "NGUYEN VAN A",
  "beneficiary_card_number": "0123456789",
  "beneficiary_bank_name": "Example Bank",
  "beneficiary_subbranch": "Hanoi",
  "notify_url": "https://merchant.example/callback/payout",
  "req_time": "1784000000",
  "nonce_str": "c4d2e19f",
  "sign": "8d93e2e107f5be2a123456789abcdef0123456789abcdef0123456789abcdef0"
}

返回参数

参数	类型	说明
`platform_order_no`	string	FluxPay 平台订单号。
`mch_order_no`	string	商户代付订单号。
`status`	string	`PAYING`、`SUCCESS` 或 `REJECTED`。
`currency`	string	银行绑定的三位大写币种。
`amount_minor`	integer	代付金额，最小货币单位整数。
`payment_method_code`	string	订单实际支付方式编码。
`bank_id`	integer	本次请求使用的平台银行或钱包 ID。
`reject_code`	string	仅驳回时返回的标准驳回代码。
`reject_reason`	string	仅驳回时返回的可读原因。
`notify_status`	string	异步通知状态。
`idempotent_replay`	boolean	是否为幂等重复提交。
`created_at`	string	订单创建时间。

成功返回示例

HTTP 200

{
  "platform_order_no": "DS000000000001001",
  "mch_order_no": "OUT202607140001",
  "status": "PAYING",
  "currency": "VND",
  "amount_minor": 250000,
  "bank_id": 7,
  "notify_status": "NOT_NOTIFIED",
  "idempotent_replay": false,
  "created_at": "2026-07-14T10:35:00Z"
}

失败返回示例

HTTP 400

{"error":"payout requires bank_id, beneficiary_name, and exactly one of beneficiary_card_number or beneficiary_qr_text"}

注意事项

不提交 product_code、country 或 currency。二维码代付时只传 beneficiary_qr_text 原文。订单可能因金额、银行或敏感收款对象规则进入人工审核，但对商户仍统一显示为 PAYING。

查询代收

根据商户代收订单号查询当前代收状态和收款信息。

接口用途

用于主动确认代收订单是否已支付。该接口只查询当前商户自己的代收订单。

请求地址和请求方式

POST/v1/payins/queryContent-Type: application/json

请求参数

参数	类型	必填	说明
`mch_id`	string	是	商户号。
`mch_order_no`	string	是	创建代收时提交的商户订单号。
`req_time` / `nonce_str` / `sign`	string	是	公共认证参数。

完整 JSON 请求示例

查询代收请求

{
  "mch_id": "1000",
  "mch_order_no": "IN202607140001",
  "req_time": "1784000060",
  "nonce_str": "payin-query-91f3",
  "sign": "b344d95123456789abcdef0123456789abcdef0123456789abcdef0123456789"
}

返回参数

参数	类型	说明
`platform_order_no`	string	平台订单号。
`mch_order_no`	string	商户代收订单号。
`status`	string	`UNPAID` 或 `PAID`。
`currency`	string	订单币种。
`amount_minor`	integer	订单金额。
`checkout_url`	string	平台统一收银台地址。
`payment_data`	object	标准化收款信息。
`notify_status`	string	通知状态。
`idempotent_replay`	boolean	查询接口固定为 `false`。
`created_at`	string	订单创建时间。

成功返回示例

HTTP 200

{
  "platform_order_no": "DS000000000001000",
  "mch_order_no": "IN202607140001",
  "status": "PAID",
  "currency": "VND",
  "amount_minor": 100000,
  "checkout_url": "https://pay.example.com/checkout/order-reference",
  "payment_data": {
    "payee_name": "NGUYEN VAN A",
    "payee_account": "0123456789",
    "bank_name": "Example Bank",
    "pay_amount": "100000",
    "qr_url": null,
    "qr_text": null,
    "payment_remark": "PAY DS000000000001000",
    "payee_account_id": null
  },
  "notify_status": "NOTIFIED_ACKNOWLEDGED",
  "idempotent_replay": false,
  "created_at": "2026-07-14T10:30:00Z"
}

失败返回示例

HTTP 404

{"error":"order not found"}

注意事项

查询代收只返回 UNPAID 或 PAID。网络超时后不要直接重新创建订单，应先使用本接口查询原商户订单号。

查询代付

根据商户代付订单号查询打款状态及驳回原因。

接口用途

用于主动确认一笔代付是打款中、成功还是驳回。该接口只查询当前商户自己的代付订单。

请求地址和请求方式

POST/v1/payouts/queryContent-Type: application/json

请求参数

参数	类型	必填	说明
`mch_id`	string	是	商户号。
`mch_order_no`	string	是	创建代付时提交的商户订单号。
`req_time` / `nonce_str` / `sign`	string	是	公共认证参数。

完整 JSON 请求示例

查询代付请求

{
  "mch_id": "1000",
  "mch_order_no": "OUT202607140001",
  "req_time": "1784000120",
  "nonce_str": "payout-query-63bd",
  "sign": "e01229f123456789abcdef0123456789abcdef0123456789abcdef0123456789"
}

返回参数

参数	类型	说明
`platform_order_no`	string	平台订单号。
`mch_order_no`	string	商户代付订单号。
`status`	string	`PAYING`、`SUCCESS` 或 `REJECTED`。
`currency`	string	订单币种。
`amount_minor`	integer	订单金额。
`bank_id`	integer	平台银行或钱包 ID。
`reject_code`	string	驳回时返回，例如 `MANUAL_REVIEW_REJECTED`。
`reject_reason`	string	驳回时返回的原因说明。
`notify_status`	string	通知状态。
`idempotent_replay`	boolean	查询接口固定为 `false`。
`created_at`	string	订单创建时间。

成功返回示例

HTTP 200 · 已驳回示例

{
  "platform_order_no": "DS000000000001001",
  "mch_order_no": "OUT202607140001",
  "status": "REJECTED",
  "currency": "VND",
  "amount_minor": 250000,
  "bank_id": 7,
  "reject_code": "MANUAL_REVIEW_REJECTED",
  "reject_reason": "人工审核不通过",
  "notify_status": "NOTIFIED_ACKNOWLEDGED",
  "idempotent_replay": false,
  "created_at": "2026-07-14T10:35:00Z"
}

失败返回示例

HTTP 404

{"error":"order not found"}

注意事项

PAYING 表示平台仍在处理，包括等待人工审核或打款中。只有 SUCCESS 和 REJECTED 是最终状态。

查询余额

查询当前商户各币种的可用余额与冻结/处理中余额。

接口用途

返回当前商户钱包余额列表。可不传币种查询全部余额，也可传指定币种过滤。

请求地址和请求方式

POST/v1/balancesContent-Type: application/json

请求参数

参数	类型	必填	说明
`mch_id`	string	是	商户号。
`currency`	string	否	三位币种代码，例如 `VND`；不传则返回全部币种。
`req_time` / `nonce_str` / `sign`	string	是	公共认证参数。

完整 JSON 请求示例

查询 VND 余额

{
  "mch_id": "1000",
  "currency": "VND",
  "req_time": "1784000180",
  "nonce_str": "balance-51a8",
  "sign": "c98e6d2123456789abcdef0123456789abcdef0123456789abcdef0123456789"
}

返回参数

参数	类型	说明
`items`	array	余额明细数组；没有余额记录时为空数组。
`items[].currency`	string	三位大写币种代码。
`items[].available_minor`	integer	当前可用余额，最小货币单位整数。
`items[].reserved_minor`	integer	冻结或处理中余额，最小货币单位整数。

成功返回示例

HTTP 200

{
  "items": [
    {
      "currency": "VND",
      "available_minor": 12500000,
      "reserved_minor": 250000
    }
  ]
}

失败返回示例

HTTP 400

{"error":"invalid currency"}

注意事项

余额字段始终为最小货币单位整数。展示金额时由商户系统根据币种的小数位规则转换，禁止在资金计算中使用二进制浮点数。

支付产品目录

公开只读目录，无需登录、商户号或签名。

创建代收时填写这里展示的产品编码

页面自动展示平台当前启用的真实支付产品。目录不提供新增、编辑或删除操作。

加载中

产品编码	支付产品名称	国家	币种	支付方式
正在加载支付产品目录…

使用说明

创建代收时填写 product_code 并从 payment_methods 选择支付方式。产品编码已绑定国家和币种，不要另外提交 country 或 currency。

银行与钱包目录

公开只读目录，无需登录、商户号或签名。

创建代付时填写这里展示的平台目标 ID

页面自动展示平台当前启用的真实银行和移动钱包。目标 ID、国家和币种用于识别代付目标。

加载中

平台目标 ID	图标	银行 / 钱包全称	简称	国家 / 币种	支付方式
正在加载银行与钱包目录…

使用说明

创建代付时将“平台目标 ID”填入 bank_id。银行目标的 beneficiary_card_number 传银行卡号；移动钱包目标传钱包绑定手机号。目标 ID 已绑定国家和币种，不要另外提交 product_code、country 或 currency。

回调通知

订单到达最终状态后，平台向创建订单时提供的 notify_url 发送 JSON POST 通知。

通知请求

项目	内容
请求方式	`POST`
Content-Type	`application/json`
`X-FluxPay-Timestamp`	RFC 3339 通知时间。
`X-FluxPay-Nonce`	本次通知唯一随机字符串。
`X-FluxPay-Signature`	`HMAC_SHA256_HEX(商户密钥, timestamp + "\n" + nonce + "\n" + raw_body)`。

通知参数

参数	类型	说明
`platform_order_no`	string	平台订单号。
`mch_order_no`	string	商户订单号。
`type`	string	`PAYIN` 或 `PAYOUT`。
`status`	string	代收为 `UNPAID/PAID`；代付为 `PAYING/SUCCESS/REJECTED`。
`currency`	string	订单币种。
`amount_minor`	integer	订单金额，最小货币单位整数。
`reject_code`	string	仅代付驳回通知包含。
`reject_reason`	string	仅代付驳回通知包含。

代收成功通知示例

POST notify_url

{
  "platform_order_no": "DS000000000001000",
  "mch_order_no": "IN202607140001",
  "type": "PAYIN",
  "status": "PAID",
  "currency": "VND",
  "amount_minor": 100000
}

商户确认响应

必须返回

HTTP/1.1 200 OK
Content-Type: text/plain

OK

失败响应示例

以下响应不会被确认

HTTP/1.1 200 OK

SUCCESS

注意事项

只有 HTTP 200 且正文去除首尾空白后严格等于 OK 才算确认成功。否则平台每 60 秒重试一次，最多 5 次。商户必须先验签，再按 platform_order_no 幂等更新本地订单。

错误码

接口失败统一返回 JSON：{"error":"具体错误说明"}。

HTTP 状态码	含义	常见原因	处理建议
`400`	参数或业务校验失败	缺少字段、金额无效、产品/银行不可用、收款信息不完整。	按 error 内容修正请求，不要原样重复提交。
`401`	认证失败	商户号、签名、时间戳或 nonce 无效。	校准服务器时间，重新生成 nonce 和签名。
`403`	访问被拒绝	代付来源 IP 不在商户白名单。	联系运营配置正确公网 IP/CIDR。
`404`	订单不存在	订单号错误，或使用错误的商户号查询。	核对 mch_order_no 和调用商户身份。
`409`	幂等冲突	同一 mch_order_no 已存在，但核心参数不同。	使用新的订单号，或恢复原订单参数。
`415`	请求格式错误	Content-Type 不是 application/json。	改为 JSON 请求体并设置正确请求头。
`429`	请求过于频繁	超过商户接口限流。	读取 Retry-After 并退避重试。
`503`	服务暂不可用	平台维护或查询依赖暂时不可用。	稍后重试；创建订单超时应先查询再决定是否重提。

失败返回示例

HTTP 401

{"error":"authentication failed"}

上线检查

确认服务端保存商户密钥、系统时间同步、每次请求 nonce 唯一、金额使用整数、代付 IP 已加入白名单、回调完成验签和幂等处理，并对创建超时执行“先查后重试”。