首页 / 开发者

五个原语，
一套 REST API。

所有接口使用 HTTPS + Bearer Token，返回 JSON。幂等键、Webhook 验签、沙箱环境一应俱全。

快速开始

在控制台「企业设置 → API 密钥」创建密钥，然后调用任意接口。沙箱密钥以 np_test_ 开头。

# 查询余额 curl https://api.novopay.group/v1/balances \ -H "Authorization: Bearer np_test_4a71…" # 返回 { "data": [ { "currency": "USD", "available": 128453000, "pending": 8620000, "reserved": 2400000 }, { "currency": "EUR", "available": 34218000, "pending": 1850000, "reserved": 0 } ] }

ⓘ金额一律以最小货币单位整数传输（美元为分），避免浮点误差。展示层再做格式化。

认证与幂等

Authorization: Bearer np_live_xxxxxxxxxxxx Idempotency-Key: "pay_2026_09_12_001" # 写接口必带，24h 内重复请求返回首次结果 X-NovoPay-Signature: t=1757654321,v1=... # Webhook 验签

同一个幂等键重复提交不会重复扣款；键相同但参数不同会返回 409 idempotency_conflict。

接口列表

GET/v1/balances多币种余额

GET/v1/accounts虚拟账户列表

POST/v1/accounts申请开立账户

POST/v1/collections创建收款链接

POST/v1/payouts创建付款

POST/v1/payouts/{id}/approve审批付款

GET/v1/transactions交易列表（分页）

GET/v1/transactions/{id}交易详情与状态链

POST/v1/beneficiaries新增受益方

POST/v1/beneficiaries/{id}/verify户名实时校验

GET/v1/fx/quote获取报价

POST/v1/fx/orders执行换汇 / 锁价

创建一个付款

curl -X POST https://api.novopay.group/v1/payouts \ -H "Authorization: Bearer np_live_…" \ -H "Idempotency-Key: po_20260912_001" \ -d '{ "beneficiary_id": "ben_8f21c", "amount": 12800000, // 128,000.00 CNY "currency": "CNY", "method": "local", // local | swift | stablecoin "source_currency": "USD", "purpose": "supplier_payment" }' // 201 Created { "id": "tx_9f2a1c", "status": "requires_approval", "quote": { "rate": 7.0759, "source_amount": 1808700 }, "risk": { "score": 34, "status": "clear" } }

!金额折合 ≥ USD 10,000 或风险分 ≥ 55 时返回 requires_approval，需要另一位成员审批后才会出款。

Webhook

事件以 POST 投递到你的 HTTPS 地址，失败按 1 分钟 / 5 分钟 / 30 分钟 / 2 小时重试，共 8 次。

验签：用 t + . + 原始报文做 HMAC-SHA256，与 v1 比对；时间戳超过 5 分钟拒绝。

错误码

400invalid_request参数缺失或格式错误

401unauthorized密钥无效或已吊销

403forbidden角色无权限（如制单人审批自己的付款）

409idempotency_conflict幂等键复用于不同参数

422insufficient_balance可用余额不足（不含冻结）

429rate_limited超出 QPS，响应头含 Retry-After

Sandbox

先写代码，
再谈生意。

沙箱密钥即刻可用，无需签约。生产密钥在 KYB 通过后签发。

获取沙箱密钥 →控制台登录

五个原语，一套 REST API。