快速上手

NeoLinks 是企业级稳定币/法币支付基础设施平台，为 B2B 商户与第三方集成方提供统一的收单、收款、付款、兑换与虚拟账户能力。通过 Partner OpenAPI，您可以在数分钟内完成沙箱集成并开始测试真实支付流程。

基础设施能力总览

环境与 Base URL

NeoLinks 提供 Sandbox 与 Production 两套环境。Sandbox 使用 stub 法币通道与 Anvil 本地链，可完整跑通 E2E 流程。

认证与签名

Partner API 使用 API Key + HMAC-SHA256 签名双重鉴权。所有写操作须携带幂等键 Idempotency-Key。

请求头

签名算法

签名字符串格式：

{timestamp}\n{METHOD}\n{path}\n{sha256(body)}

curl -X POST "https://api.sandbox.neolinks.io/v1/acquiring/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pk_sandbox_xxx" \
  -H "X-Timestamp: 2026-06-22T08:00:00Z" \
  -H "X-Signature: a1b2c3..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"merchant_order_id":"ord_001","amount":"100.00","currency":"USDC","payment_method":"crypto","chain_id":31337,"notify_url":"https://example.com/webhook"}'

通用响应格式

所有 API 响应均为 JSON，包含统一信封字段。成功时 code = 0，错误时 code 为字符串错误码。

{
  "code": 0,
  "message": "ok",
  "data": { /* 业务对象 */ },
  "trace_id": "tr_abc123",
  "request_id": "req_xyz789"
}

{
  "code": "INVALID_REQUEST",
  "message": "amount must be a positive decimal string",
  "trace_id": "tr_abc123",
  "request_id": "req_xyz789"
}

幂等与限流

幂等规则

默认限流

收单 Acquiring

收单模块支持平台内 Invoices/Transactions 与 Partner OpenAPI 双订单源。创建订单后系统自动分配稳定币 Vault 地址或法币虚拟账户，并通过 Webhook 推送状态变更。

订单状态机

虚拟账户 Virtual Account

法币收单通过虚拟账户（VA）实现美元代收。创建 payment_method: "fiat" 的收单订单后，系统自动分配路由银行账号，付款方通过银行转账完成支付，附言（payment_reference）用于自动匹配。

VA 付款指引字段

法币收单响应中的 va / fiat_payment 对象包含以下字段：

{
  "merchant_order_id": "mch_fiat_001",
  "amount": "5000.00",
  "currency": "USD",
  "payment_method": "fiat",
  "notify_url": "https://merchant.example.com/webhook"
}

{
  "code": 0,
  "data": {
    "id": "acq_ord_fiat001",
    "status": "AWAITING_PAYMENT",
    "payment_rail": "fiat",
    "va": {
      "bank_name": "Community Federal Savings Bank",
      "account_name": "NeoLinks Payments LLC",
      "account_number": "****7890",
      "swift": "CMFGUS33",
      "payment_reference": "QX-ACQ-abc123",
      "global_account_id": "ga_usd_001"
    }
  }
}

收款 Collection

独立收款账户模块，适用于非收单场景的稳定币入账。创建收款单后分配 HD 子地址，链上确认 + KYT 通过后入账至收款账户（RECEIVE）。

付款 Payout

向受益人发起银行出款或链上 payout。扣款源可选收单清算户（ACQUIRING）、收款户（RECEIVE）或兑换交割户（EXCHANGE）。材料审核通过后由商户门户或 Partner API 执行。

{
  "debit_business_account": "ACQUIRING",
  "amount": "1000.00",
  "currency": "USDC",
  "beneficiary_name": "Acme Corp",
  "beneficiary_account": "0xRecipient..."
}

兑换 Exchange

实时锁价兑换，支持法币与稳定币互换。创建兑换单锁定汇率，确认后执行；失败自动回滚账务分录。

入金 Deposits

入金记录查询接口，用于 T+1 对账。包含链上入账与 VA 法币入账的统一视图。

余额 Balances

按币种与业务账户汇总可用余额，只读接口。付款前建议调用以确保余额充足。

{
  "code": 0,
  "data": [
    {
      "currency": "USDC",
      "business_account": "ACQUIRING",
      "available": "12500.00"
    },
    {
      "currency": "USD",
      "business_account": "ACQUIRING",
      "available": "50000.00"
    }
  ]
}

稳定币收单

稳定币收单通过 Vault 智能合约接收链上 USDC/USDT 等代币。创建订单后返回 pay_contract（Vault 地址）与 order_ref（bytes32 订单引用），付款方调用 Vault.pay(orderRef, amount) 完成支付。

• Scanner 实时监听链上 PaymentReceived 事件
• 入账后触发 KYT 筛查，通过后状态流转至 COMPLETED
• 资金归集至商户收单清算账户（ACQUIRING）
• 本地开发使用 Anvil（chain_id=31337），生产环境按 configs/chains.yaml 配置

法币收单

法币收单通过虚拟账户（VA）路由实现。开发阶段使用 stub 模式模拟银行入账回调，生产环境对接真实 VA/银行通道 adapter。

• 创建订单时 payment_method: "fiat"，无需 chain_id
• 响应包含完整 VA 付款指引（银行名、账号、附言）
• VA Webhook 入账后自动匹配订单，支持部分/超额到账
• 通道模式由环境变量 VA_WEBHOOK_* / BANK_PAYOUT_MODE 控制

保证金

收单业务可配置保证金要求。保证金不足时 API 返回 MARGIN_INSUFFICIENT（HTTP 403）。商户可通过商户门户或 Partner API 进行保证金充值（margin top-up）。

KYT 合规

所有链上入账均触发 KYT（Know Your Transaction）筛查。KYT 为异步流程，订单状态先进入 KYT_PENDING，筛查完成后流转至 COMPLETED 或 KYT_FAILED。

• KYT 供应商通过 adapter 端口接入，开发阶段使用 stub 模式
• 拒绝时推送 acquiring.order.kyt_failed Webhook
• AML 冻结由运营后台人工触发，优先级高于 Payment 操作

Webhook 事件

订单状态变更时，NeoLinks 向创建订单时指定的 notify_url 投递 JSON 事件。所有 Webhook 均经 Outbox 异步投递，支持指数退避重试。

事件列表

{
  "event": "acquiring.order.completed",
  "created_at": "2026-06-22T08:00:00Z",
  "data": {
    "id": "acq_ord_abc123",
    "merchant_order_id": "mch_ord_001",
    "status": "COMPLETED",
    "amount": "100.00",
    "currency": "USDC"
  }
}

签名验证

Webhook 请求携带以下 Header，接收方须验证签名以确保来源可信：

重试策略：1m → 5m → 30m → 2h → 8h。商户返回 HTTP 2xx 视为投递成功。

错误码

Sandbox 测试

Sandbox 环境提供完整的 stub 法币通道与 Anvil 本地链，可跑通收单/收款/付款/兑换全链路 E2E。

快速开始

1. 联系销售获取 Sandbox API Key 与 Secret
2. 阅读「认证与签名」章节，按 HMAC 规范构造请求头
3. 创建 crypto 收单订单，使用 Anvil 测试账户向 Vault 地址转账
4. 创建 fiat 收单订单，使用 stub VA 模拟入账回调
5. 配置 Webhook 接收端点，验证签名与事件流转

# quantiex-platform 仓库
make up              # Postgres + Redis
make up-anvil        # 本地链 RPC :8545
make migrate         # 数据库迁移
make deploy-anvil    # 部署 Vault 合约
make smoke-anvil-chain  # 链上 E2E 冒烟

更新日志