快速上手

NeoLinks 商户 BFF 覆盖收单、收款、付款、法币换汇与账户。当前对外契约是 /api/merchant/v1，鉴权为登录会话 Bearer。Partner HMAC 尚未开放。

能力总览

环境与 Base URL

对外商户 API 挂在官网同源路径下。下文接口路径均相对此 Base URL；本地联调见「本地联调」。

认证

先 POST /auth/login 拿会话 token，之后请求带 Authorization: Bearer <token>。写接口另需对应 mch:* 权限。

请求头

curl -X POST "https://neolinks.io/api/merchant/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"password1"}'

curl -X POST "https://neolinks.io/api/merchant/v1/acquiring/invoices" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv-001" \
  -d '{"amount_due_minor":100000000,"currency":"USDC","payment_rail":"CRYPTO","chain_id":31337}'

通用响应格式

成功时 HTTP 2xx 且 code = 0（整数）。错误时 HTTP 4xx/5xx，code 为字符串错误码。

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

{
  "code": "GATE_DENIED",
  "message": "no active ACQUIRING_CRYPTO behavior",
  "trace_id": "tr_abc123",
  "request_id": "req_xyz789"
}

幂等与金额单位

幂等

金额单位

收单 Acquiring

资源名为发票 /acquiring/invoices（/acquiring/orders 为同处理器别名）。建单前须有对应 active Behavior（CRYPTO 或 FIAT）。

订单状态

虚拟账户 Virtual Account

法币收单 / 收款使用 VA。创建时必须 payment_rail: "FIAT"，且该币种 Capability 已开通。响应永不返回完整账号。

FIAT 发票字段

{
  "amount_due_minor": 500000,
  "currency": "USD",
  "payment_rail": "FIAT"
}

收款 Collection

独立收款单，不是收单发票。CRYPTO 分配地址；FIAT 返回掩码 VA。客户支付匹配入 crypto_inbounds / fiat_inbounds，不是充值。

付款 Payout

对手必须是本公司已核验 payees（purpose=PAYOUT）。禁止手填地址/账号。CRYPTO 扣 TREASURY 并进入材料审核；BANK 无 chain_id。

{
  "payee_account_id": "pae_...",
  "amount_minor": 100000000,
  "currency": "USDC",
  "rail": "CRYPTO",
  "chain_id": 31337
}

兑换 Exchange

已开通的 FIAT_FX / CRYPTO_SWAP / ONRAMP / OFFRAMP 走 stub 询价再下单。扣款户只能是 TREASURY。未开通或已停用的类型返回 403 GATE_DENIED。source_amount_minor / target_amount_minor 按各币种最小单位；跨法币↔稳定币时目标金额会按汇率并换算 scale（法币×100，稳定币×1e6）。

充值 Deposits

GET /deposits 只表示真实充值。客户付到 Vault、Vault→清算都不是充值，不会出现在此列表。

余额 Balances

按业务账户查询可用余额。query business_account：ACQUIRING / COLLECTION / TREASURY / EXCHANGE。

稳定币收单

开通 ACQUIRING_CRYPTO 后建 CRYPTO 发票。付款方对 Vault 调用 pay(orderRef, amount)。Scanner 写入 crypto_inbounds 并匹配订单。

• 匹配成功 → inbound MATCHED，订单离开纯待付
• Vault→清算完结订单，禁止记两条假充值
• 本地 Anvil chain_id=31337

法币收单

先开通 ACQUIRING_FIAT（按币种 scope）。建单必须显式 payment_rail=FIAT，且 currency 为 USD/EUR/HKD。

• 响应只有掩码账号与 fiat_payment_ref
• 入账通道默认 stub，不阻塞功能验收
• 本环境 Webhook 不含法币超额 / 充值入账事件

开通 Capability

无对应 active 细 Behavior 时建单 403 GATE_DENIED。KYB 须 APPROVED。

Webhook 事件

在门户「设置 → Webhook」或 PATCH /integration/webhook 配置 URL。本环境只投递下列三条收单事件。

本环境已推送

不投递：收款 / 付款 / 兑换、deposit_credited、法币超额、KYT 失败。

{
  "event": "acquiring.order.completed",
  "id": "ao_...",
  "status": "COMPLETED",
  "amount_due_minor": 100000000,
  "currency": "USDC",
  "order_ref": "0x..."
}

签名验证

首次保存配置会返回一次明文 secret。签名：

接收方返回 HTTP 2xx 视为成功。轮换密钥：POST /integration/webhook/rotate。

错误码

本地联调

在 neolinks-core 仓库启动 Docker API 与商户门户即可对照本文档调接口。

1. make up && make up-app-skip-build && make web-restart
2. POST /auth/login 获取 Bearer token
3. 确认 KYB APPROVED 且已开通对应 Capability
4. 创建 CRYPTO 发票，用 Anvil 钱包向 Vault 支付
5. PATCH /integration/webhook 后观察三条收单事件

# neolinks-core 仓库
make up                 # Postgres + Redis
make up-anvil           # 本地链 RPC :8545
make up-app-skip-build  # Docker API :8080
make web-restart        # 商户 :3000 / 运营 :3001

更新日志