{ "openapi": "3.0.3", "info": { "title": "HissPay Merchant API", "version": "1.12.0", "description": "2026-10-01 生产接口契约。产品目录不等于商户可交易：须同时具备有效商户币种、协议、路由与渠道。实际配置和示例见 README.md。代收成功按 realAmount 核对，代付超时保留待查。1.0.3 为纯文档兼容性新增：产品目录标明 LIVE（可用）/ PLANNED（即将开放，不可下单）/ BLOCKED（暂不可用，不可下单）；补充按支付方式的下单要求与下单结果不确定时的处理。签名、nonce、字段类型与必填项均未改变。 1.1.0 新增：payType 枚举与币种范围；merchantOrderNo 最长 255、product 最长 20；clientIp 须为合法 IPv4/IPv6，notifyUrl/returnUrl 非空时须为合法 http(s) URL（参数错误均为业务码 400）；USDT 代收（currency=USDT，product 为 USDT-TRON/USDT-ETHEREUM/USDT-BSC/USDT-SOLANA，金额最多 4 位小数），代收下单响应新增 product、paymentInfo，查单响应新增 product、txHash，成功通知有链上确认时追加 txHash；新增业务码 10013（通道尚未接入，不建单），10006 文案改为 Amount not allowed。签名与 nonce 规则未改变。 1.2.0 变更：代付最低金额规则：通道下限由平台为通道配置，未配置时按币种默认（AUD、USD 1.00；INR、PKR、BDT 及其他币种 100.00），平台可为通道设置其他值；签约可配置更高下限；实际下限取两者中的较高者，低于下限返回 10006（msg 形如 The minimum payout amount is 1.00 AUD.）。签名、nonce、字段类型与必填项均未改变。 1.3.0 变更（纯文档，按现行生产代码补齐）：AUD-VKDPWMRT（澳洲银行卡）下单要求——payType 必须显式为 CARD；clientIp 必填（键名区分大小写，须为付款人 IP 字面量）；returnUrl 必填且为 HTTPS；phone 为 5–15 位纯数字；金额 1–500 AUD 且为整数或 .99；cardExtra 为 JSON 字符串，顶层恰好 connection_info、account_info（键、取值与长度规则见 README 第 6 节「澳洲银行卡（AUD-VKDPWMRT）」）。错误码补充 9999（系统异常；当前部分下单参数不合规也返回 9999，见 README 第 11 节「9999 自查清单」）、999（功能未实现）、500（系统异常）、404/405、47001/47014/47015（交易条款，开关启用时）；10021 改为按现状描述（非空白且格式非法，或部分产品缺少付款人 IP；AUD-VKDPWMRT 缺失 clientIp，含空串和全空白，当前返回 9999）；AUD-VKDPWMRT 的 9999 只在通过通用校验（400/10006/10012/10021 等）之后出现。签名、nonce、字段类型与通用必填项均未改变。 1.12.0 变更（纯文档，按现行生产代码修正）：新增币种 THB 与 THB 产品（目录见 info.x-product-catalog.products，由产品目录自动生成）；同单号再次下单返回 10020（仅个别产品启用业务幂等时同参返回原结果、改参 409）；nonce 重复返回 400 nonce has been used、900 仅并发、防重放窗口 60 秒；请求体含 null 返回 400；代付类接口 msg 统一改写（Invalid payout request / Payout request rejected / Payout request not confirmed; query original order），THB 代付字段不合规的返回形式见 README 第 11 节「代付下单的拒绝与 msg」；代收 product 最长 64、代付 20；免填 bizCode/branchCode 须 payCode=CARD 且产品与币种匹配；APPLE_PAY 适用 USD、AUD；部分通道发送代收失败通知，查单 payStatus 可为 2 并返回 failureCode；新增沙箱接口 /transaction/sandbox/v1/network。签名算法、字段类型与必填项未改变。", "x-product-catalog": { "statuses": { "LIVE": "可用；仍须商户签约、开通币种并有可用路由才能交易", "PLANNED": "即将开放，不可下单", "BLOCKED": "暂不可用，不可下单" }, "products": [ { "code": "AUD-PAYPLUS-APPLE-M85", "currency": "AUD", "direction": "PAYIN", "status": "LIVE" }, { "code": "AUD-PAYPLUS-GOOGLE-M85", "currency": "AUD", "direction": "PAYIN", "status": "LIVE" }, { "code": "AUD-VKDPWMRT", "currency": "AUD", "direction": "PAYIN", "status": "LIVE" }, { "code": "INR-HBGMMNKI", "currency": "INR", "direction": "PAYIN", "status": "LIVE" }, { "code": "INR-NPLMSUEX", "currency": "INR", "direction": "PAYOUT", "status": "LIVE" }, { "code": "THB-PROMPTPAY-PAYIN", "currency": "THB", "direction": "PAYIN", "status": "LIVE" }, { "code": "USD-EKCBBONA", "currency": "USD", "direction": "PAYIN", "status": "LIVE" }, { "code": "EUR-CARD-PAYIN", "currency": "EUR", "direction": "PAYIN", "status": "PLANNED" }, { "code": "GBP-CARD-PAYIN", "currency": "GBP", "direction": "PAYIN", "status": "PLANNED" }, { "code": "JPY-CARD-PAYIN", "currency": "JPY", "direction": "PAYIN", "status": "PLANNED" }, { "code": "THB-BANK-PAYOUT", "currency": "THB", "direction": "PAYOUT", "status": "PLANNED" }, { "code": "USD-APPLEPAY-PAYIN", "currency": "USD", "direction": "PAYIN", "status": "PLANNED" }, { "code": "USD-CARD-PAYIN", "currency": "USD", "direction": "PAYIN", "status": "PLANNED" }, { "code": "USD-CASHAPP-PAYIN", "currency": "USD", "direction": "PAYIN", "status": "PLANNED" }, { "code": "USD-HOSTED-PAYIN", "currency": "USD", "direction": "PAYIN", "status": "PLANNED" }, { "code": "USD-LOCAL-PAYOUT", "currency": "USD", "direction": "PAYOUT", "status": "PLANNED" }, { "code": "USDT-BSC", "currency": "USDT", "direction": "PAYIN", "status": "PLANNED" }, { "code": "USDT-ETHEREUM", "currency": "USDT", "direction": "PAYIN", "status": "PLANNED" }, { "code": "USDT-SOLANA", "currency": "USDT", "direction": "PAYIN", "status": "PLANNED" }, { "code": "USDT-TRON", "currency": "USDT", "direction": "PAYIN", "status": "PLANNED" }, { "code": "AUD-CARD", "currency": "AUD", "direction": "PAYIN", "status": "BLOCKED" }, { "code": "AUD-LOCAL-PAYOUT", "currency": "AUD", "direction": "PAYOUT", "status": "BLOCKED" }, { "code": "BDT-LOCAL-PAYIN", "currency": "BDT", "direction": "PAYIN", "status": "BLOCKED" }, { "code": "BDT-LOCAL-PAYOUT", "currency": "BDT", "direction": "PAYOUT", "status": "BLOCKED" }, { "code": "IDR-LOCAL-PAYIN", "currency": "IDR", "direction": "PAYIN", "status": "BLOCKED" }, { "code": "IDR-LOCAL-PAYOUT", "currency": "IDR", "direction": "PAYOUT", "status": "BLOCKED" }, { "code": "PHP-LOCAL-PAYIN", "currency": "PHP", "direction": "PAYIN", "status": "BLOCKED" }, { "code": "PHP-LOCAL-PAYOUT", "currency": "PHP", "direction": "PAYOUT", "status": "BLOCKED" }, { "code": "PKR-LOCAL-PAYIN", "currency": "PKR", "direction": "PAYIN", "status": "BLOCKED" }, { "code": "PKR-LOCAL-PAYOUT", "currency": "PKR", "direction": "PAYOUT", "status": "BLOCKED" } ] } }, "servers": [ { "url": "{gateway}", "description": "Production / 生产网关（登录商户后台「应用密钥」页面查看）", "variables": { "gateway": { "default": "https://GATEWAY_FROM_MERCHANT_PORTAL" } } } ], "tags": [ { "name": "payin", "description": "代收" }, { "name": "payout", "description": "代付及余额" } ], "paths": { "/transaction/payin/v1/apply": { "post": { "operationId": "payin_apply", "summary": "创建代收订单", "tags": [ "payin" ], "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "description": "生产交易接口。下单前确认币种、产品、路由、费率和额度。请求头 appId、timestamp、nonce、sign 均必填；timestamp 为 Unix 毫秒且偏差不超过 30 秒，nonce 至少 10 字符并在 60 秒内不可重用。目录项与支付方式枚举均不保证生产可交易；以实际商户协议、币种、路由及渠道为准；目录中 PLANNED、BLOCKED 产品不可下单。结果不确定（超时、断线、HTTP 5xx、非 JSON）时订单可能已经创建：保留原 merchantOrderNo，以验签通过的回调或查单为准，不要再次调用本接口——既不要换新订单号重下，也不要用同一订单号重下。同一订单号再次下单返回 10020（启用业务幂等的产品改参返回 409）。", "x-payment-method-requirements": { "common": "只传本接口字段；上游所需参数由平台配置，商户不传。订单币种必须是该产品的币种。金额主币种最多两位小数，超精度被拒；零小数位币种格式待确认。name/email/phone 须为付款人真实信息。returnUrl 用公网 HTTPS，部分托管收银台产品付款后不跳回。不要提交卡号、CVV 或钱包凭据。结果只以回调或查单为准；失败或过期不发通知，payStatus 可能长期为 0。", "card_with_cart": "部分银行卡代收产品要求在 cardExtra（字符串）中提交购物车（商品编号、名称、单价、数量）和购物者信息（名、姓、付款人公网 IP、邮箱；按产品要求：电话、账单地址、城市、邮编、国家、州或省；可选：收货地址、浏览器 UA 与语言、商户侧客户编号）。cardExtra 缺失或不全时下单会被拒绝。cardExtra 内部键名和编码格式待确认。payUrl 为托管支付页 HTTPS 地址，可能不在 HissPay 域名下。", "aud_card": "AUD-VKDPWMRT（澳洲银行卡托管支付）：payType 必须显式传 CARD；clientIp 必填（键名精确为 clientIp，真实付款人 IP 字面量，放在请求体）；returnUrl 必填，https、主机名含点且非 localhost、无用户信息、端口省略或 443、不超过 512 字符；phone 5–15 位纯数字（不带 +、空格、横线、国家码）；email 不超过 254 字符；金额 1–500 AUD，整数或 .99；name 仍必填但不使用，addr 不使用；cardExtra 必填，为 JSON 字符串，顶层恰好 connection_info、account_info；merchant_user_id 与 email、phone 一一绑定。仅支持澳洲手机号（area_code 固定 61）与澳洲账单信息（country=AU）；海外手机号/海外账单地址暂不支持。错误码按校验顺序返回：先过通用校验，不合规时返回原有业务码（必填为空、URL 非法 → 400；金额 ≤0 或精度超限 → 10006；payType 与币种不匹配或为空字符串 → 10012；clientIp 非空白且格式非法 → 10021；产品、协议、路由问题 → 10004、10005 等）；只有通过通用校验后，在本产品校验中不满足上述要求，当前才返回 9999。完整规则与示例见 README 第 6 节「澳洲银行卡（AUD-VKDPWMRT）」。", "hosted_checkout": "返回 payUrl 后引导付款人整页跳转或新窗口打开（iframe 待确认）；链接有有效期，因支付方式而异；跳回 returnUrl 不代表已付款；以代收成功通知或 payStatus=1 为准并按 realAmount 入账；放弃或过期时先联系平台确认原单关闭，再用新的 merchantOrderNo 下单。", "subscription": "没有订阅或定期扣款接口；不要用本接口模拟订阅。" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinRequest" }, "example": { "merchantOrderNo": "DEMO_IN_001", "amount": "100.00", "currency": "INR", "product": "INR-HBGMMNKI", "name": "Test User", "phone": "YOUR_TEST_PHONE", "email": "payer@example.com", "notifyUrl": "https://merchant.example.com/notify" } } } }, "responses": { "200": { "description": "同时检查业务code和订单状态。HTTP200不代表支付成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinApplyResponse" } } } }, "default": { "description": "错误或结果未知；超时请查原单，不自动重付。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transaction/payin/v1/query": { "post": { "operationId": "payin_query", "summary": "查询代收订单", "tags": [ "payin" ], "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "description": "按appId每个查询接口每秒最多5次；建议低频轮询。请求头 appId、timestamp、nonce、sign 均必填；timestamp 为 Unix 毫秒且偏差不超过 30 秒，nonce 至少 10 字符并在 60 秒内不可重用。同时传两个订单号时必须对应同一笔订单。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "example": { "merchantOrderNo": "DEMO_IN_001" } } } }, "responses": { "200": { "description": "同时检查业务code和订单状态。HTTP200不代表支付成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinQueryResponse" } } } }, "default": { "description": "错误或结果未知；超时请查原单，不自动重付。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transaction/payout/v1/apply": { "post": { "operationId": "payout_apply", "summary": "创建代付订单", "tags": [ "payout" ], "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "description": "生产交易接口。下单前确认币种、产品、路由、费率和额度。超时或响应不确定时保留原订单号查单，不能直接重发、换号、换渠道或解冻；仅确认原单终态失败并核对资金后才可另建新单。请求头 appId、timestamp、nonce、sign 均必填；timestamp 为 Unix 毫秒且偏差不超过 30 秒，nonce 至少 10 字符并在 60 秒内不可重用。目录项与支付方式枚举均不保证生产可交易；以实际商户协议、币种、路由及渠道为准。 USD银行卡代付仅在平台明确开通后支持：payCode=CARD，extra为JSON字符串，仅含平台已绑定的beneficiary_id正整数和card_valid(MM/YYYY)。不支持该产品批量代付或商户自助创建受益人。代付类接口为避免回显收款人资料会改写 msg：通用校验 400 Invalid payout request，业务拒绝保留业务码、msg Payout request rejected，500 Payout request not confirmed; query original order。THB 代付见 README 16.4。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutRequest" }, "examples": { "generic": { "summary": "通用代付结构", "value": { "merchantOrderNo": "DEMO_OUT_001", "amount": "100.00", "currency": "INR", "product": "INR-NPLMSUEX", "accountName": "RECIPIENT_NAME", "account": "RECIPIENT_ACCOUNT", "phone": "RECIPIENT_PHONE", "email": "recipient@example.com", "bizCode": "ASSIGNED_BIZ_CODE", "payCode": "ASSIGNED_PAY_CODE", "branchCode": "RECIPIENT_IFSC" } }, "usdCard": { "summary": "USD银行卡结构（待平台开通及替换占位值）", "value": { "merchantOrderNo": "MERCHANT_OUT_UNIQUE_001", "amount": "100.00", "currency": "USD", "product": "USD-PAYPLUS-PAYOUT", "accountName": "RECIPIENT_NAME", "account": "RECIPIENT_CARD_NUMBER", "phone": "RECIPIENT_PHONE", "email": "recipient@example.com", "payCode": "CARD", "notifyUrl": "https://merchant.example.com/payout/notify", "extra": "{\"beneficiary_id\":12345,\"card_valid\":\"12/2030\"}" } } } } } }, "responses": { "200": { "description": "同时检查业务code和订单状态。HTTP200不代表支付成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutApplyResponse" } } } }, "default": { "description": "错误或结果未知；超时请查原单，不自动重付。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transaction/payout/v1/query": { "post": { "operationId": "payout_query", "summary": "查询代付订单", "tags": [ "payout" ], "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "description": "按appId每个查询接口每秒最多5次；建议低频轮询。请求头 appId、timestamp、nonce、sign 均必填；timestamp 为 Unix 毫秒且偏差不超过 30 秒，nonce 至少 10 字符并在 60 秒内不可重用。同时传两个订单号时必须对应同一笔订单。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "example": { "merchantOrderNo": "DEMO_OUT_001" } } } }, "responses": { "200": { "description": "同时检查业务code和订单状态。HTTP200不代表支付成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutQueryResponse" } } } }, "default": { "description": "错误或结果未知；超时请查原单，不自动重付。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transaction/payout/v1/balance": { "post": { "operationId": "payout_balance", "summary": "查询账户余额", "tags": [ "payout" ], "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "description": "按appId每个查询接口每秒最多5次；建议低频轮询。请求头 appId、timestamp、nonce、sign 均必填；timestamp 为 Unix 毫秒且偏差不超过 30 秒，nonce 至少 10 字符并在 60 秒内不可重用。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceRequest" }, "example": { "currency": "INR" } } } }, "responses": { "200": { "description": "同时检查业务code和订单状态。HTTP200不代表支付成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } }, "default": { "description": "错误或结果未知；超时请查原单，不自动重付。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transaction/sandbox/v1/network": { "post": { "operationId": "sandbox_network", "tags": [ "sandbox" ], "summary": "查看平台看到的来源 IP", "description": "仅独立HissPay沙箱环境可用，生产不存在。必须使用独立沙箱应用签名，请求体为 {}。返回 data.environment（sandbox）与 data.sourceIp（平台看到的调用方公网出口 IP，用于配置沙箱代付白名单）。", "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "code=0 时 data 含 environment、sourceIp。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "sandbox" ] }, "sourceIp": { "type": "string" } } } } } } } }, "default": { "description": "400 参数/签名、429 限流。" } } } }, "/transaction/sandbox/v1/query": { "post": { "operationId": "sandbox_query", "tags": [ "sandbox" ], "summary": "查看模拟场景与渠道投递记录", "description": "仅独立HissPay沙箱环境可用，生产不存在。必须使用独立沙箱应用签名。type=payout对应代付。仅能访问当前应用自己的模拟订单；404不区分不存在和无权限。trigger仅适用于尚未终态的手动场景，resend限10秒一次/每单20次。模拟投递日志不是商户回调接收证明。", "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "merchantOrderNo" ], "properties": { "type": { "type": "string", "enum": [ "payin", "payout" ] }, "merchantOrderNo": { "type": "string", "description": "当前应用原商户订单号" } } } } } }, "responses": { "200": { "description": "检查code=0与data；HTTP200不代表真实到账。query含scenario、simStatus、triggerAllowed、resendAllowed、deliveries。" }, "default": { "description": "400参数/签名、404无可访问模拟订单、48001状态不允许、429限流。" } } } }, "/transaction/sandbox/v1/trigger": { "post": { "operationId": "sandbox_trigger", "tags": [ "sandbox" ], "summary": "手动触发模拟终态", "description": "仅独立HissPay沙箱环境可用，生产不存在。必须使用独立沙箱应用签名。type=payout对应代付。仅能访问当前应用自己的模拟订单；404不区分不存在和无权限。trigger仅适用于尚未终态的手动场景，resend限10秒一次/每单20次。模拟投递日志不是商户回调接收证明。", "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "merchantOrderNo", "event" ], "properties": { "type": { "type": "string", "enum": [ "payin", "payout" ] }, "merchantOrderNo": { "type": "string", "description": "当前应用原商户订单号" }, "event": { "type": "string", "enum": [ "PAID", "FAILED" ] } } } } } }, "responses": { "200": { "description": "检查code=0与data；HTTP200不代表真实到账。query含scenario、simStatus、triggerAllowed、resendAllowed、deliveries。" }, "default": { "description": "400参数/签名、404无可访问模拟订单、48001状态不允许、429限流。" } } } }, "/transaction/sandbox/v1/resend": { "post": { "operationId": "sandbox_resend", "tags": [ "sandbox" ], "summary": "重发最近模拟终态", "description": "仅独立HissPay沙箱环境可用，生产不存在。必须使用独立沙箱应用签名。type=payout对应代付。仅能访问当前应用自己的模拟订单；404不区分不存在和无权限。trigger仅适用于尚未终态的手动场景，resend限10秒一次/每单20次。模拟投递日志不是商户回调接收证明。", "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "merchantOrderNo" ], "properties": { "type": { "type": "string", "enum": [ "payin", "payout" ] }, "merchantOrderNo": { "type": "string", "description": "当前应用原商户订单号" } } } } } }, "responses": { "200": { "description": "检查code=0与data；HTTP200不代表真实到账。query含scenario、simStatus、triggerAllowed、resendAllowed、deliveries。" }, "default": { "description": "400参数/签名、404无可访问模拟订单、48001状态不允许、429限流。" } } } }, "/transaction/payout/v1/beneficiaries/create": { "post": { "operationId": "beneficiary_create", "summary": "创建收款人", "tags": [ "payout" ], "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "description": "须平台开放后使用；仅USD/US银行卡。operation参与签名且必须匹配路径。payeeId不可变且只在当前应用/产品/环境使用。结果未知时查询同一payeeId，不自动重建或更新。version必须为JSON整数，更新提交完整资料；已用于出款的记录不能更新。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryCreateRequest" }, "example": { "operation": "CREATE", "product": "ASSIGNED_PRODUCT", "payeeId": "customer_10001", "language": "en", "country": "US", "phone": "12025550123", "birthdate": "1990-01-01", "email": "recipient@example.com", "firstName": "Jane", "lastName": "Doe", "zip": "10001", "city": "New York", "state": "NY", "address": "123 Example Street" } } } }, "responses": { "200": { "description": "同时检查业务code和data.status；仅READY且beneficiaryId非空可用于代付。NOT_FOUND不授权自动重复创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryResponse" } } } }, "default": { "description": "错误或结果未知；超时请查原单，不自动重付。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transaction/payout/v1/beneficiaries/query": { "post": { "operationId": "beneficiary_query", "summary": "查询收款人", "tags": [ "payout" ], "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "description": "须平台开放后使用；仅USD/US银行卡。operation参与签名且必须匹配路径。payeeId不可变且只在当前应用/产品/环境使用。结果未知时查询同一payeeId，不自动重建或更新。version必须为JSON整数，更新提交完整资料；已用于出款的记录不能更新。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryQueryRequest" }, "example": { "operation": "QUERY", "product": "ASSIGNED_PRODUCT", "payeeId": "customer_10001" } } } }, "responses": { "200": { "description": "同时检查业务code和data.status；仅READY且beneficiaryId非空可用于代付。NOT_FOUND不授权自动重复创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryResponse" } } } }, "default": { "description": "错误或结果未知；超时请查原单，不自动重付。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transaction/payout/v1/beneficiaries/update": { "post": { "operationId": "beneficiary_update", "summary": "更新收款人资料", "tags": [ "payout" ], "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "应用标识，不是商户号" }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix毫秒时间戳，时间差不超过30秒" }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "至少10字符的新随机数，不得重用" }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SHA256(排序后的请求体及三个签名头键值串直接追加appSecret)，小写hex；请使用下载示例签名" } ], "description": "须平台开放后使用；仅USD/US银行卡。operation参与签名且必须匹配路径。payeeId不可变且只在当前应用/产品/环境使用。结果未知时查询同一payeeId，不自动重建或更新。version必须为JSON整数，更新提交完整资料；已用于出款的记录不能更新。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryUpdateRequest" }, "example": { "operation": "UPDATE", "product": "ASSIGNED_PRODUCT", "payeeId": "customer_10001", "language": "en", "country": "US", "phone": "12025550123", "birthdate": "1990-01-01", "email": "recipient@example.com", "firstName": "Jane", "lastName": "Doe", "zip": "10001", "city": "New York", "state": "NY", "address": "123 Example Street", "version": 0, "requestId": "change_10001_001" } } } }, "responses": { "200": { "description": "同时检查业务code和data.status；仅READY且beneficiaryId非空可用于代付。NOT_FOUND不授权自动重复创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryResponse" } } } }, "default": { "description": "错误或结果未知；超时请查原单，不自动重付。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "PayinRequest": { "type": "object", "required": [ "merchantOrderNo", "amount", "currency", "product", "name", "phone", "email", "userId" ], "properties": { "merchantOrderNo": { "type": "string", "description": "商户唯一订单号，最长 255 字符，超长返回业务码 400。同一应用下已存在的单号再次下单返回 10020（无论参数是否相同）；仅平台为产品单独启用业务幂等时，同参返回原受理结果、改参返回 409（以开通通知为准）。", "maxLength": 255 }, "amount": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, { "type": "number" } ], "description": "币种主单位，推荐十进制字符串100.00；INR不是paise；AUD按澳元，100澳元传100.00，不是10000。零小数币种(JPY/KRW/VND等)必须为整数（否则 10006），其余法币最多两位小数；三位小数币种暂不支持。USDT 最多 4 位小数（四个网络一致），最小 0.0001；超出精度返回 10006。" }, "currency": { "type": "string", "description": "币种三位大写字母，或资产代码 USDT；生产目录目前包含 AUD、BDT、IDR、INR、PHP、PKR、THB、USD，仅已签约且具备可用路由的组合可交易。USDT 代收固定为 USDT。四字母代码只支持 USDT，其他返回 10006。" }, "product": { "type": "string", "description": "按代收方向选择已签约产品编码，最长 64 字符，超长返回业务码 400；目录存在不表示开通。USDT 代收为 USDT-TRON、USDT-ETHEREUM、USDT-BSC、USDT-SOLANA；THB 代收编码见 info.x-product-catalog。具体编码与配置状态见 README.md 第 1 节。", "maxLength": 64 }, "phone": { "type": "string", "description": "手机号，必填。AUD-VKDPWMRT 只能是 5–15 位纯数字，不带 +、空格、横线和国家码 61。" }, "email": { "type": "string", "description": "付款人邮箱，必填；不传或空字符串返回业务码 400（email invalid）。" }, "userId": { "type": "string", "maxLength": 32, "description": "商户侧付款用户的唯一标识，必填；同一付款人保持不变，参与签名。超过 32 个字符返回业务码 400。" }, "notifyUrl": { "type": "string", "format": "uri", "description": "本单通知地址，未提供时使用商户默认地址；建议公网 HTTPS。非空时（空字符串视为未填）必须是合法 http(s) URL，否则返回业务码 400（HTTP 200，JSON code=400）。" }, "name": { "type": "string", "description": "付款人姓名。THB 代收为付款银行账户户名（README 16.3）。" }, "returnUrl": { "type": "string", "format": "uri", "description": "浏览器返回地址；推荐公网 HTTPS，部分通道可能要求必填；非空时（空字符串视为未填）必须是合法 http(s) URL，否则返回业务码 400（HTTP 200，JSON code=400），不强制 HTTPS。部分托管收银台产品付款后不跳回；跳回不代表已付款。AUD-VKDPWMRT 必填，且必须为 https、主机名含点且非 localhost、无用户信息、端口省略或 443、不超过 512 字符。非空且不是合法 http(s) URL 仍返回 400；不传、空字符串，或是合法 URL 但不满足上述本产品要求时，当前返回 9999。" }, "addr": { "type": "string", "description": "" }, "payType": { "type": "string", "description": "可选；不传时按产品路由。显式传入时校验编码与币种的组合，不匹配返回 10012：CARD（24 币）、PAYPAL（20 币）、CASHAPP（USD）、GOOGLE_PAY（USD/EUR/GBP/JPY/AUD）、APPLE_PAY（USD/AUD）、CASH（USD/AUD/EUR/GBP/INR/BDT/PKR/PHP/IDR）、HOSTED（USD/AUD/EUR/GBP）、CRYPTO（USDT）、WALLET（INR）、JAZZCASH/EASYPAISA（PKR）、BKASH/NAGAD（BDT）。枚举匹配不代表该币种/产品有生产可用通道，须以商户签约与平台开通为准。不使用时请省略字段；传空字符串同样返回 10012。AUD-VKDPWMRT 必须显式传 CARD：不传时订单按 WALLET 记录，当前返回 9999。 THB 代收请勿传 payType（README 16.3）。", "enum": [ "CARD", "PAYPAL", "CASHAPP", "GOOGLE_PAY", "APPLE_PAY", "CASH", "HOSTED", "CRYPTO", "WALLET", "JAZZCASH", "EASYPAISA", "BKASH", "NAGAD" ] }, "otherExtend": { "type": "string", "description": "不保证查单或回调携带" }, "cardExtra": { "type": "string", "description": "通道扩展。字符串，原样参与签名（取 JSON 解码后的字符串值本身；签名后不要重新序列化）；不要写成 JSON 对象或数组（写成对象或数组可能返回 500）。AUD-VKDPWMRT 必填：值为序列化后的 JSON 文本，解析后顶层恰好 connection_info、account_info 两个对象；connection_info 必填 country=\"AU\"、state（NSW/VIC/QLD/ACT/NT/SA/TAS/WA）、zip_code（4 位数字）、media_source（1–64 位字母数字_-），可选 user_agent（≤1024）、uuid（≤64）、language（≤16，如 en-AU）；account_info 必填 merchant_user_id（≤64）、create_time（JSON 整数毫秒时间戳，≥1000000000000 且不晚于当前时间，用户在商户侧的注册时间）、role（GUEST/PRIVATE）、area_code=\"61\"（字符串）、first_name、last_name（≤64，仅英文字母、空格、'、-）；不允许其他键；文本值不得为空白、含控制字符、含 cvv/cvc/card number/security code 字样或疑似卡号；总长 ≤8192 UTF-8 字节；不满足当前返回 9999（规则详见 README 第 6 节「澳洲银行卡（AUD-VKDPWMRT）」）。其他部分银行卡代收产品（即将开放）用于提交购物车和购物者信息，内部键名和编码格式待确认，使用前确认。 THB 代收必填：值为恰好含 payerAccountNo（6–20 位数字）与 payerBankCode（SCB/KBANK/KTB/BAY/GSB/TTB）两个字符串键的 JSON 文本，不超过 512 字符（README 16.3）。" }, "clientIp": { "type": "string", "maxLength": 45, "description": "真实付款人公网 IP；键名区分大小写，必须写作 clientIp（写成 client_ip、clientIP、ip 等会被忽略）。值非空白时必须是合法 IPv4 或 IPv6 文本，格式非法或超过 45 字符均返回 10021（不是 400）；空字符串或全空白在这一步按未传处理。部分要求必填的产品缺少可用付款人 IP 时也返回 10021。AUD-VKDPWMRT 必填，须为付款人 IP 字面量（IPv4 用点分形式）；不传、null、空字符串、全空白或键名错误都视为缺失，当前返回 9999。", "example": "203.0.113.10" } } }, "PayoutRequest": { "type": "object", "required": [ "merchantOrderNo", "amount", "currency", "product", "accountName", "account", "phone", "email", "accountId", "payCode" ], "properties": { "merchantOrderNo": { "type": "string", "description": "商户唯一订单号，最长 255 字符，超长返回业务码 400。同一应用下已存在的单号再次下单返回 10020（无论参数是否相同）；仅平台为产品单独启用业务幂等时，同参返回原受理结果、改参返回 409（以开通通知为准）。", "maxLength": 255 }, "amount": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$" }, { "type": "number" } ], "description": "主币种金额，须大于 0 且不低于代付最低金额。通道下限由平台为代付通道配置，未配置时为该币种默认值：AUD、USD 为 1.00；INR、PKR、BDT 为 100.00；其他币种为 100.00（平台可为通道设置其他值，可高于或低于默认值）。签约下限为商户签约中配置的最低金额，未配置时不额外限制。实际下限取通道下限与签约下限中的较高者（签约下限低于通道下限时按通道下限），并仍需满足签约路由额度。低于下限返回 10006；代付接口 msg 统一为 Payout request rejected（见 README 第 4、11 节）" }, "currency": { "type": "string", "description": "币种三位大写字母；生产目录目前包含 AUD、BDT、IDR、INR、PHP、PKR、THB、USD，仅已签约且具备可用路由的组合可交易。" }, "product": { "type": "string", "description": "已签约的代付产品编码；目录存在不表示开通，编码见 README 第 1 节与 info.x-product-catalog。最长 20 字符，超长返回业务码 400。", "maxLength": 20 }, "phone": { "type": "string", "description": "手机号，必填" }, "email": { "type": "string", "description": "收款人邮箱，必填。" }, "notifyUrl": { "type": "string", "format": "uri", "description": "本单通知地址，未提供时使用商户默认地址；建议公网 HTTPS。" }, "accountName": { "type": "string", "description": "收款账户户名，必填。THB：泰文或英文字母、空格、. ' -，首字符为字母；长度上限按付款通道不同（部分通道默认 10 个字符），以开通通知为准（README 16.4）。" }, "account": { "type": "string", "description": "银行或支付账号，保留前导零" }, "bizCode": { "type": "string", "description": "条件必填：仅当 payCode=CARD 且 (product,currency) 为 (USD-PAYPLUS-PAYOUT,USD)、(USD-LOCAL-PAYOUT,USD) 或 (AUD-LOCAL-PAYOUT,AUD) 时新订单可省略；其余情况缺失或为空返回业务码 400。已有订单重试保持首次原值。 THB 固定 BANK。" }, "payCode": { "type": "string", "description": "平台分配支付方式，不能为空。THB 代付填 BANK。" }, "branchCode": { "type": "string", "description": "条件必填：仅当 payCode=CARD 且 (product,currency) 为 (USD-PAYPLUS-PAYOUT,USD)、(USD-LOCAL-PAYOUT,USD) 或 (AUD-LOCAL-PAYOUT,AUD) 时新订单可省略；其余情况缺失或为空返回业务码 400。已有订单重试保持首次原值。 THB 填银行编码（README 16.1），须在开通通知的可用银行内。" }, "bankName": { "type": "string", "description": "银行名称，视通道要求；最长 255 字符，超长返回业务码 400。", "maxLength": 255 }, "address": { "type": "string", "description": "" }, "accountId": { "type": "string", "description": "收款人在商户系统中的唯一标识，必填；同一收款人保持不变，平台按通道要求作为收款用户标识上送。" }, "swiftCode": { "type": "string", "description": "" }, "extra": { "type": "string", "description": "扩展信息字符串。已开通USD银行卡代付时必填，内容为仅含beneficiary_id正整数和card_valid(MM/YYYY)的JSON；必须使用收款人创建/查询接口返回 READY、绑定于本应用/产品/环境的 beneficiaryId。字符串整体参与签名，不展开内层字段。" } }, "anyOf": [ { "properties": { "product": { "enum": [ "USD-PAYPLUS-PAYOUT", "USD-LOCAL-PAYOUT" ] }, "currency": { "enum": [ "USD" ] }, "payCode": { "enum": [ "CARD" ] } } }, { "properties": { "product": { "enum": [ "AUD-LOCAL-PAYOUT" ] }, "currency": { "enum": [ "AUD" ] }, "payCode": { "enum": [ "CARD" ] } } }, { "required": [ "bizCode", "branchCode" ] } ] }, "QueryRequest": { "type": "object", "properties": { "merchantOrderNo": { "type": "string", "description": "商户单号" }, "orderNo": { "type": "string", "description": "平台订单号；若同时传 merchantOrderNo，二者必须对应同一笔订单。" } }, "anyOf": [ { "required": [ "merchantOrderNo" ] }, { "required": [ "orderNo" ] } ], "description": "merchantOrderNo 与 orderNo 至少提供一个；同时提供时必须指向同一订单，否则业务码 30001。" }, "BalanceRequest": { "type": "object", "required": [ "currency" ], "properties": { "currency": { "type": "string", "description": "商户已开立账户的币种；查询余额不证明该币种有可交易产品。" } } }, "Error": { "type": "object", "properties": { "code": { "type": "integer", "description": "0 成功；其余为业务码，见 README 第 11 节。新增 10013：通道尚未接入，不建单。1.3.0 补充：9999 系统异常（当前部分下单参数不合规也返回 9999）、999 功能未实现、500 系统异常、404/405、47001/47014/47015。 1.12.0：10020、900、48001（仅沙箱）含义按现行代码修正，见 README 第 11 节。" }, "msg": { "type": "string", "description": "" }, "data": { "nullable": true } }, "description": "业务错误。常见 code：400 参数/签名不合法（HTTP 200、JSON code=400；含 merchantOrderNo 超 255、代收 product 超 64、代付 product 超 20、notifyUrl/returnUrl 非空且非法 URL，msg 形如请求参数不正确:merchantOrderNo too long）；10020 同一应用下商户订单号已存在；409 启用业务幂等的产品同单号参数不一致、收款人接口冲突或结果未确认；900 并发重复请求（已用 nonce 再次使用为 400 nonce has been used）；10006 Amount not allowed（超出路由金额范围或币种精度，含零小数币非整数；代付金额低于最低金额（通道下限与签约下限中的较高者），代付接口 msg 为 Payout request rejected）；10012 payType 与币种不匹配或为空字符串；10013 通道尚未接入（产品已配置但通道未接入，订单未创建，视为暂不可用）；10021 clientIp 非空白且格式非法（含超过 45 字符），或部分要求必填的产品缺少可用付款人 IP（AUD-VKDPWMRT 缺失 clientIp，即不传、null、空字符串、全空白或键名错误，当前返回 9999，不是 10021）；9999 系统异常：已通过通用校验（上列 400、10006、10012、10021 等不会以 9999 返回），但在产品自身校验中不合规的下单参数当前也可能返回 9999（如 AUD-VKDPWMRT 的 cardExtra 缺失或格式不对、clientIp 缺失或键名错误、payType 不是 CARD、phone/email/returnUrl/金额不合规），平台正在改为具体业务码；收到后先用原 merchantOrderNo 查单，不要换单号重付，按 README 第 11 节「9999 自查清单」处理；999 功能未实现（所路由的支付通道不支持该操作，联系平台）；500 系统异常（如请求体无法按字段类型解析），按结果不确定处理；代付接口 500 msg 为 Payout request not confirmed; query original order，原单查单持续 30001 即未建单（README 第 11 节「代付下单的拒绝与 msg」）；47001/47014/47015 交易条款未配置/冲突/不支持（平台为商户启用新结算条款后可能返回，订单未创建）；其余见 README 第 11 节。" }, "PayinApplyResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string", "description": "" }, "data": { "type": "object", "properties": { "appId": { "type": "string", "description": "" }, "merchantOrderNo": { "type": "string", "description": "" }, "orderNo": { "type": "string", "description": "" }, "currency": { "type": "string", "description": "" }, "product": { "type": "string", "description": "本单产品编码，所有代收下单响应均返回。" }, "amount": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, { "type": "number" } ], "description": "币种主单位，推荐十进制字符串100.00；INR不是paise；AUD按澳元，100澳元传100.00，不是10000。响应中为 JSON 数字（BigDecimal），请用 Decimal 解析；USDT 最多 4 位小数。" }, "payStatus": { "type": "integer", "enum": [ 0 ], "description": "已创建，不代表收款成功" }, "payUrl": { "type": "string", "format": "uri", "description": "付款页地址。托管收银台产品为 HTTPS 托管支付页，可能不在 HissPay 域名下，且有有效期；访问该页不代表已付款。" }, "paymentInfo": { "type": "object", "description": "USDT 收款信息；仅 USDT 产品且平台已分配收款地址时返回，不适用时不返回该键。返回时 6 个字段全部输出。网络由 product 确定。", "properties": { "asset": { "type": "string", "enum": [ "USDT" ] }, "network": { "type": "string", "enum": [ "TRON", "ETHEREUM", "BSC", "SOLANA" ] }, "address": { "type": "string", "description": "本订单收款地址" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$", "description": "应收 USDT 金额，字符串，最多 4 位小数" }, "qrCodeImage": { "type": "string", "nullable": true, "description": "预留字段，当前版本恒为 null；请按 address 与 amount 自行生成二维码" }, "expiresAt": { "type": "string", "format": "date-time", "description": "收款地址有效期，UTC ISO 8601；由平台给出，可能为 null", "nullable": true } }, "required": [ "asset", "network", "address", "amount", "qrCodeImage", "expiresAt" ] }, "otherExtend": { "type": "string", "description": "" } } } } }, "PayoutApplyResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string", "description": "" }, "data": { "type": "object", "properties": { "appId": { "type": "string", "description": "" }, "merchantOrderNo": { "type": "string", "description": "" }, "orderNo": { "type": "string", "description": "" }, "currency": { "type": "string", "description": "" }, "amount": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$" }, { "type": "number" } ], "description": "币种主单位，推荐十进制字符串100.00；INR不是paise；AUD按澳元，100澳元传100.00，不是10000。" }, "payStatus": { "type": "integer", "enum": [ 0 ], "description": "受理后异步处理" } } } } }, "PayinQueryResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string", "description": "" }, "data": { "type": "object", "properties": { "appId": { "type": "string", "description": "" }, "merchantOrderNo": { "type": "string", "description": "" }, "orderNo": { "type": "string", "description": "" }, "currency": { "type": "string", "description": "" }, "product": { "type": "string", "description": "本单产品编码；当前订单均返回，历史归档订单可能为 null。", "nullable": true }, "amount": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, { "type": "number" } ], "description": "原订单金额，主币种单位，始终与下单金额一致。响应中为 JSON 数字（BigDecimal），请用 Decimal 解析；USDT 最多 4 位小数。" }, "realAmount": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, { "type": "number" } ], "description": "核验后的实际收款总额，主币种单位、扣费前，可小于或大于amount。仅payStatus=1且本字段为有效正数时按此金额幂等入账；缺失或非法不得回退使用amount。响应中为 JSON 数字，USDT 最多 4 位小数。未成功的订单可能为 0。", "nullable": true }, "payStatus": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "0 未报告成功（含处理中、待核对、取消、部分 FAILED）；1 已收款；2 部分通道明确确认付款失败。以 paymentStatus/isFinal 为准。" }, "txHash": { "type": "string", "description": "USDT 代收链上确认后的交易哈希；法币或确认前不适用时不返回该键。" }, "paymentStatus": { "type": "string", "enum": [ "CREATED", "PROCESSING", "PENDING_CONFIRMATION", "SUCCEEDED", "CANCELLED", "FAILED", "UNKNOWN" ], "description": "兼容扩展状态；忽略未知字段。CANCELLED不证明上游未扣款。" }, "isFinal": { "type": "boolean", "description": "是否有明确最终结果。false不得自动重付。" }, "failureReason": { "type": "string", "description": "可选，仅供展示和排查：可能是大写原因码或英文短句，不含上游敏感错误内容；不要据此做程序判断。" }, "failureCode": { "type": "string", "enum": [ "PAYMENT_DECLINED", "PAYMENT_RISK_REJECTED", "PAYMENT_FAILED" ], "description": "可选；通道明确确认付款失败时给出。" } } } } }, "PayoutQueryResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string", "description": "" }, "data": { "type": "object", "properties": { "appId": { "type": "string", "description": "" }, "merchantOrderNo": { "type": "string", "description": "" }, "orderNo": { "type": "string", "description": "" }, "currency": { "type": "string", "description": "" }, "amount": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$" }, { "type": "number" } ], "description": "币种主单位，推荐十进制字符串100.00；INR不是paise；AUD按澳元，100澳元传100.00，不是10000。" }, "payStatus": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "0处理中/结果未知（含超时待查），禁止重发或退款；1成功；2明确失败。超时、5xx、一次查无此单都不是失败终态。" }, "payStatusDes": { "type": "string", "description": "" }, "paymentStatus": { "type": "string", "enum": [ "CREATED", "PROCESSING", "PENDING_CONFIRMATION", "SUCCEEDED", "CANCELLED", "FAILED", "UNKNOWN" ], "description": "兼容扩展状态；忽略未知字段。CANCELLED不证明上游未扣款。" }, "isFinal": { "type": "boolean", "description": "是否有明确最终结果。false不得自动重付。" }, "failureReason": { "type": "string", "description": "可选固定原因码，不含上游敏感错误内容。" } } } } }, "BalanceResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string", "description": "" }, "data": { "type": "object", "properties": { "appId": { "type": "string", "description": "" }, "accountNo": { "type": "string", "description": "" }, "currency": { "type": "string", "description": "" }, "balance": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$" }, { "type": "number" } ], "description": "币种主单位，推荐十进制字符串100.00；INR不是paise；AUD按澳元，100澳元传100.00，不是10000。" }, "balanceActive": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$" }, { "type": "number" } ], "description": "币种主单位，推荐十进制字符串100.00；INR不是paise；AUD按澳元，100澳元传100.00，不是10000。" }, "balanceFreeze": { "oneOf": [ { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$" }, { "type": "number" } ], "description": "币种主单位，推荐十进制字符串100.00；INR不是paise；AUD按澳元，100澳元传100.00，不是10000。" } } } } }, "BeneficiaryCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "operation", "product", "payeeId", "language", "country", "phone", "birthdate", "email", "firstName", "lastName", "zip", "city", "state", "address" ], "properties": { "operation": { "type": "string", "minLength": 1, "enum": [ "CREATE" ] }, "product": { "type": "string", "minLength": 1, "maxLength": 20 }, "payeeId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_-]{3,60}$" }, "language": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^(?:[a-zA-Z]{2})$" }, "country": { "type": "string", "minLength": 1, "enum": [ "US" ], "maxLength": 2 }, "phone": { "type": "string", "minLength": 1, "maxLength": 17, "pattern": "^(?:(\\+[0-9]{1,3}-)?[0-9]{4,12})$" }, "birthdate": { "type": "string", "minLength": 1, "format": "date", "maxLength": 10 }, "email": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^(?:[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.(?:[a-zA-Z]{2,}|xn--[a-zA-Z0-9]+))$" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^(?:[A-Za-zÀ-ÿß'-][A-Za-zÀ-ÿß '-]{1,48}[A-Za-zÀ-ÿß'-])$" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^(?:[A-Za-zÀ-ÿß'-][A-Za-zÀ-ÿß '-]{1,48}[A-Za-zÀ-ÿß'-])$" }, "zip": { "type": "string", "minLength": 1, "maxLength": 10, "pattern": "^(?:[0-9]{5}(?:-[0-9]{4})?|[0-9]{5,10})$" }, "city": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^(?:[A-Za-zÀ-ÿß'&()\\-][A-Za-zÀ-ÿß '&()\\-]{0,48}[A-Za-zÀ-ÿß'&()\\-])$" }, "state": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^(?:[A-Za-zÀ-ÿß'&()\\-][A-Za-zÀ-ÿß '&()\\-]{0,48}[A-Za-zÀ-ÿß'&()\\-])$" }, "address": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^(?:[0-9A-Za-zÀ-ÿß #'(),\\-./:;°]{5,100})$" } } }, "BeneficiaryQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "operation", "product", "payeeId" ], "properties": { "operation": { "type": "string", "minLength": 1, "enum": [ "QUERY" ] }, "product": { "type": "string", "minLength": 1, "maxLength": 20 }, "payeeId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_-]{3,60}$" } } }, "BeneficiaryUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "operation", "product", "payeeId", "language", "country", "phone", "birthdate", "email", "firstName", "lastName", "zip", "city", "state", "address", "version", "requestId" ], "properties": { "operation": { "type": "string", "minLength": 1, "enum": [ "UPDATE" ] }, "product": { "type": "string", "minLength": 1, "maxLength": 20 }, "payeeId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_-]{3,60}$" }, "language": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^(?:[a-zA-Z]{2})$" }, "country": { "type": "string", "minLength": 1, "enum": [ "US" ], "maxLength": 2 }, "phone": { "type": "string", "minLength": 1, "maxLength": 17, "pattern": "^(?:(\\+[0-9]{1,3}-)?[0-9]{4,12})$" }, "birthdate": { "type": "string", "minLength": 1, "format": "date", "maxLength": 10 }, "email": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^(?:[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.(?:[a-zA-Z]{2,}|xn--[a-zA-Z0-9]+))$" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^(?:[A-Za-zÀ-ÿß'-][A-Za-zÀ-ÿß '-]{1,48}[A-Za-zÀ-ÿß'-])$" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^(?:[A-Za-zÀ-ÿß'-][A-Za-zÀ-ÿß '-]{1,48}[A-Za-zÀ-ÿß'-])$" }, "zip": { "type": "string", "minLength": 1, "maxLength": 10, "pattern": "^(?:[0-9]{5}(?:-[0-9]{4})?|[0-9]{5,10})$" }, "city": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^(?:[A-Za-zÀ-ÿß'&()\\-][A-Za-zÀ-ÿß '&()\\-]{0,48}[A-Za-zÀ-ÿß'&()\\-])$" }, "state": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^(?:[A-Za-zÀ-ÿß'&()\\-][A-Za-zÀ-ÿß '&()\\-]{0,48}[A-Za-zÀ-ÿß'&()\\-])$" }, "address": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^(?:[0-9A-Za-zÀ-ÿß #'(),\\-./:;°]{5,100})$" }, "version": { "type": "integer", "minimum": 0, "format": "int64", "maximum": 9223372036854775806 }, "requestId": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_-]{3,60}$" } } }, "BeneficiaryResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "payeeId": { "type": "string" }, "beneficiaryId": { "type": [ "integer", "null" ], "minimum": 1 }, "status": { "type": "string", "enum": [ "READY", "UNKNOWN", "NOT_FOUND", "REVIEW" ] }, "version": { "type": "integer", "minimum": 0 } } } } } } }, "webhooks": { "payinSuccess": { "post": { "summary": "代收结果通知（成功；部分通道另发失败通知）", "description": "平台发送到本单 notifyUrl 或商户默认地址。头部按请求签名规则验签；仅非 null 的 body 字段参与签名。HTTP 2xx 且响应体原样为 OK 或 SUCCESS（大小写不敏感）才确认送达。法币金额字符串固定两位小数；USDT 金额固定 4 位小数。有链上交易哈希时追加 txHash 字段并参与签名。部分通道在明确确认付款失败时发送 status=2、realAmount=0.00 的失败通知；扩展形态另含 eventId、eventType=PAYIN_FAILED、paymentStatus=FAILED、isFinal=true、failureCode、failureReason（全部非 null 字段参与签名，见 README 第 10 节「代收失败通知」）。不跟随重定向，单次请求约 10 秒超时，最多投递 5 次。", "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "merchantOrderNo", "orderNo", "product", "amount", "realAmount", "status" ], "properties": { "currency": { "type": "string" }, "merchantOrderNo": { "type": "string" }, "orderNo": { "type": "string" }, "product": { "type": "string" }, "amount": { "type": "string" }, "realAmount": { "type": "string" }, "status": { "type": "string", "description": "\"1\" 成功；\"2\" 失败（仅部分通道发送）" }, "txHash": { "type": "string", "description": "USDT 代收链上确认后的交易哈希；仅在有值时出现，出现即参与签名。" }, "eventId": { "type": "string", "description": "失败通知扩展形态：事件唯一标识" }, "eventType": { "type": "string", "description": "失败通知扩展形态：PAYIN_FAILED" }, "paymentStatus": { "type": "string", "description": "失败通知扩展形态：FAILED" }, "isFinal": { "type": "string", "description": "失败通知扩展形态：\"true\"" }, "failureCode": { "type": "string", "description": "失败通知扩展形态：PAYMENT_DECLINED / PAYMENT_RISK_REJECTED / PAYMENT_FAILED" }, "failureReason": { "type": "string", "description": "失败通知扩展形态：英文说明，仅供展示" } } }, "example": { "currency": "INR", "merchantOrderNo": "DEMO_IN_001", "orderNo": "PLATFORM_ORDER_NO", "product": "INR-HBGMMNKI", "amount": "100.00", "realAmount": "100.00", "status": "1" }, "x-usdt-example": { "currency": "USDT", "merchantOrderNo": "DEMO_USDT_20261001_001", "orderNo": "PLATFORM_ORDER_NO", "product": "USDT-TRON", "amount": "12.3456", "realAmount": "12.3456", "status": "1", "txHash": "CHAIN_TRANSACTION_HASH" } } } }, "responses": { "200": { "description": "纯文本 OK 或 SUCCESS；无空格或换行", "content": { "text/plain": { "schema": { "type": "string", "enum": [ "OK", "SUCCESS" ] } } } } } } }, "payoutResult": { "post": { "summary": "代付成功或失败通知", "description": "签名与 ACK 规则同代收通知。utr 可为 null，此时不参与签名；status 1 成功、2 失败。", "parameters": [ { "name": "appId", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "sign", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "merchantOrderNo", "orderNo", "product", "amount", "status", "statusDes" ], "properties": { "currency": { "type": "string" }, "merchantOrderNo": { "type": "string" }, "orderNo": { "type": "string" }, "product": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "string" }, "statusDes": { "type": "string" }, "utr": { "type": "string", "nullable": true } } }, "example": { "currency": "INR", "merchantOrderNo": "DEMO_OUT_001", "orderNo": "PLATFORM_ORDER_NO", "product": "INR-NPLMSUEX", "amount": "100.00", "utr": null, "status": "1", "statusDes": "Success" } } } }, "responses": { "200": { "description": "纯文本 OK 或 SUCCESS；无空格或换行", "content": { "text/plain": { "schema": { "type": "string", "enum": [ "OK", "SUCCESS" ] } } } } } } } } }