介绍

通过买家已经在用的钱包 App 收款:Venmo、Cash App、Zelle、PayPal、Chime、Revolut、Wise、Monzo、N26。付款经零知识证明验证后,资金点对点直达你指定的链上钱包。买家也可以直接用链上钱包付数字货币,或用 Apple Pay。

besofinance.peer 在 Peer 支付网络之上提供统一 API:你只对接我们一套接口和一套密钥,每个商户在支付网络上有自己独立的收款账户(子账户),资金不经过我们,直接结算到你的钱包。

买家付款方式

一笔支付如何完成

1. 你的后端创建订单
   调用 POST /v1/orders(或 SDK 的 createCheckout),传入金额,得到结账页地址 checkoutUrl。
2. 买家选择钱包
   买家在结账页看到金额,选择自己的付款 App 或数字货币,生成一次支付尝试(payment)。
3. 买家完成付款
   按页面指引在自己的 App 里转账,无需注册账户。
4. 零知识证明验证
   系统用零知识证明确认付款真实发生,不泄露买家账户信息。
5. 结算与通知
   USDC 结算到你的钱包,我们向你的服务器发送签名的 ORDER_FULFILLED Webhook。

两种验证方式

接入方式

上线前准备

• 在 商家后台 提交开户申请,审核通过并开通后登录。
• 开通时会生成首期订阅账单(1,000 美元 / 月),在后台“账单”页付款;保持订阅有效。
• 在后台“开发者”页生成沙盒 API 密钥(公钥 + 私钥),注册沙盒 Webhook。
• 用沙盒跑通完整流程(可用 沙盒测试单 一键结算),再生成正式密钥上线。
• 可选:在“开发者”页为正式密钥设置 IP 白名单。

快速开始

1. 拿到密钥

在商家后台“开发者 → API 密钥”创建一把沙盒密钥,得到公钥 beso_pk_test_… 和私钥 beso_sk_test_…。私钥只显示一次,保存到服务器环境变量:

BESO_API_KEY=beso_pk_test_xxxxxxxx
BESO_API_SECRET=beso_sk_test_xxxxxxxx
BESO_WEBHOOK_SECRET=whsec_xxxxxxxx   # 注册 Webhook 时返回

2. 安装 SDK

npm install @besofinance/peer-sdk

需要 Node.js 18 及以上。SDK 会自动为每个请求签名(见 鉴权与请求签名)。Python / PHP / Go 见 多语言 SDK。

3. 创建结账

import { BesoClient } from '@besofinance/peer-sdk';

const beso = new BesoClient({
  apiBaseUrl: 'https://api.peer.besofinance.xyz/v1',
  apiKey: process.env.BESO_API_KEY,
  apiSecret: process.env.BESO_API_SECRET,
});

const order = await beso.createCheckout({
  requestedAmount: '50.00',
  requestedCurrency: 'USD',
  reference: 'ORDER-1001',          // 你的订单号,同时是幂等键
  settleChain: 8453,                  // 可选,数字链 ID;不传用开户时登记的收款钱包
  settleToken: 'USDC',
  successUrl: 'https://yoursite.com/orders/1001',
  notes: { customerId: 'C-88' },
});

4. 跳转到结账页

// 后端把 order.checkoutUrl 返回给前端
window.location.href = order.checkoutUrl;

5. 处理 Webhook

在你的服务器上提供一个接口,先验证签名,再监听 ORDER_FULFILLED 事件,把订单标记为已支付。详见 验签。

6. 端到端测试

// 沙盒:新建一张 10 美元的测试单并直接结算,触发真实签名的 ORDER_FULFILLED
await beso.sandboxTestOrder({ amount: '10.00' });
// 或者结算你刚用 createCheckout 建的那张单
await beso.sandboxTestOrder({ orderId: order.id });

开户、订阅与环境

开户流程

1. 提交申请
   在 login.html 的“申请开户”页填写公司、联系邮箱、网站、行业、预计月交易额、收款钱包和后台登录密码;或调用 POST /v1/onboarding/applications(无需密钥)。
2. 审核
   Besofinance 审核(KYB)。状态:pending_review → approved / rejected。审核期间可以登录后台查看进度,但不能生成密钥、不能调用 API(403 MERCHANT_NOT_ACTIVE)。
3. 开设收款账户
   审核通过后,Besofinance 在支付网络上为你开设独立的子账户(沙盒 + 正式各一个)。每个子账户有自己的 API 密钥和结算通知签名密钥,与其他商户完全隔离;收款设置(含手续费由谁承担,默认商户承担)沿用平台账户。
4. 支付网络店铺审核
   正式收款前,支付网络还会审核你的店铺资料(网站、经营内容等)。审核期间沙盒可正常联调,正式环境状态为 pending_peer_review,不能生成正式密钥,正式环境建单返回 403 PEER_REVIEW_PENDING。审核通过(approved)后自动解除。当前状态见 GET /v1/merchants/me 的 liveReviewStatus。
5. 开通与首期账单
   开通后状态变为 active,系统生成首期订阅账单(结账链接),付款后即可使用。
6. 生成密钥
   在后台“开发者”页按环境生成 API 密钥(每个环境最多 5 把有效密钥;正式密钥需店铺审核通过)。

开户申请接口

POST https://api.peer.besofinance.xyz/v1/onboarding/applications
Content-Type: application/json

{
  "companyName": "Acme Ltd",
  "contactEmail": "ops@acme.com",
  "password": "至少 10 位,用于登录商家后台",
  "website": "https://acme.com",
  "industry": "电商",
  "country": "SG",
  "expectedMonthlyVolume": "50000",
  "note": "可选备注",
  "payoutAddress": "0x…",
  "payoutChainId": 8453,
  "payoutToken": "USDC"
}

返回 201 与 { merchantId, onboardingStatus: "pending_review" }。同一邮箱重复申请返回 409 APPLICATION_EXISTS;每个 IP 每分钟最多 10 次。

订阅计费

停用期间仍可用的接口:GET /merchants/me、订阅与账单、/integration/status、Webhook 配置与投递日志、退款申请。被 Besofinance 人工冻结(风控)时所有接口返回 403 MERCHANT_SUSPENDED。

沙盒与正式环境

环境由密钥决定,无需额外参数。响应里的订单、Webhook 事件都带 environment 字段(SANDBOX / LIVE)。商家后台用右上角的环境开关切换。

SDK 参考

请在后端创建订单,API 私钥只能保存在服务器端。Node.js 包名 @besofinance/peer-sdk(0.2+ 自动签名)。所有函数都有两种写法:函数式 createCheckout(params, opts),或面向对象 new BesoClient(opts).createCheckout(params)。

客户端参数

函数

错误处理

import { BesoApiError } from '@besofinance/peer-sdk';

try {
  await beso.createCheckout(params);
} catch (error) {
  if (error instanceof BesoApiError) {
    console.error(error.statusCode, error.errorCode, error.fieldErrors);
    if (error.errorCode === 'SUBSCRIPTION_EXPIRED') { /* 提醒续费 */ }
  }
}

BesoApiError 包含:statusCode、errorCode、message、fieldErrors、formErrors、responseObject。PeerApiError 是它的别名,旧代码无需修改;另提供与 Peer SDK 同名的别名 PayApiError,从 @zkp2p/pay-sdk 迁移时只需改 import。

电商插件与多语言 SDK

插件和 SDK 的源码都在交付包的 plugins/ 与 sdk/ 目录中,全部对接本页的统一 API(公钥 + 私钥签名),收到 ORDER_FULFILLED 后把订单置为已支付。

插件统一的配置项:API 基础地址、公钥、私钥、Webhook 签名密钥;可选:结算链 ID、结算币种、收款地址(不填用开户时登记的钱包)。

AI 辅助接入

如果你习惯用 AI 编程助手,可以把下面这段提示词交给它,让它按我们的文档,在你的项目里完成 SDK 安装、创建结账、跳转和 Webhook 验签。

使用步骤

1. 准备密钥
   在商家后台“开发者 → API 密钥”生成沙盒密钥(公钥 + 私钥)。
2. 放进环境变量
   写到项目的 .env:BESO_API_KEY、BESO_API_SECRET、BESO_WEBHOOK_SECRET。
3. 交给 AI
   把下面的提示词发给你的 AI 编程助手,并让它在你的项目目录里工作。
4. 本地验证
   用沙盒跑通:创建结账 → 调用沙盒测试单结算 → 收到 ORDER_FULFILLED Webhook。
5. 切换正式环境
   确认无误后,换成正式密钥上线。

提示词模板

请帮我在当前项目里接入 besofinance.peer 的支付 API。要求:

1. 安装 npm 包 @besofinance/peer-sdk(Node.js 18+),用 new BesoClient({ apiBaseUrl,
   apiKey, apiSecret }) 创建客户端;SDK 会自动给每个请求加 X-Timestamp / X-Nonce /
   X-Signature 签名。
2. API 基础地址 https://api.peer.besofinance.xyz/v1 ;公钥从环境变量 BESO_API_KEY、
   私钥从 BESO_API_SECRET 读取,不要写进代码,不要让我把密钥贴给你。
3. 在后端新增创建订单接口:调用 createCheckout,传 requestedAmount + requestedCurrency
   (或 requestedUsdcAmount)、reference(我们自己的订单号,用作幂等键)、successUrl、notes。
   把返回的 checkoutUrl 给前端跳转。successUrl 只是“返回商户”链接,不会自动跳转。
4. 新增 Webhook 接收接口:读取原始请求体,用 X-Webhook-Timestamp 与 X-Webhook-Signature
   做 HMAC-SHA256 验签(签名内容为 timestamp + "." + 原始请求体,十六进制;secret 来自
   BESO_WEBHOOK_SECRET),时间戳误差超过 5 分钟就拒绝;用 X-Webhook-Id 去重;先返回 2xx
   再异步处理;只在收到 ORDER_FULFILLED 时才把订单标记为已支付并发货(用 data.order.reference
   或 data.order.id 对应到我们的订单)。
5. 接口调用失败时捕获 BesoApiError,记录 statusCode 与 errorCode;402 SUBSCRIPTION_EXPIRED
   表示订阅到期。
6. 全程使用沙盒密钥测试:调用 POST /v1/sandbox/test-order 结算测试单,并给我一份本地测试步骤。

只做以上 SDK 与 API 密钥的接入,不要改动与支付无关的代码。

它能做什么,不能做什么

API 参考 · 鉴权与请求签名

API 密钥

• 每把密钥由公钥(beso_pk_test_… / beso_pk_live_…)和私钥(beso_sk_test_… / beso_sk_live_…)组成,在商家后台“开发者 → API 密钥”创建。私钥只在创建或轮换时显示一次。
• 公钥放在请求头 X-API-Key;私钥不随请求发送,只用来计算签名。
• 密钥决定环境:test = 沙盒,live = 正式。每个环境最多 5 把有效密钥。
• 仅限服务器端使用,不要放进浏览器或手机 App。

请求签名

每个带密钥的请求都必须带以下三个请求头:

待签名串 = X-Timestamp + "\n"
         + X-Nonce     + "\n"
         + 大写 HTTP 方法(GET / POST / PATCH / DELETE)+ "\n"
         + 请求路径和查询串(以 /v1 开头,如 /v1/merchants/me/orders?page=2)+ "\n"
         + hex(SHA256(原始请求体))      # 没有请求体时是空串的 SHA256

X-Signature = hex(HMAC-SHA256(私钥, 待签名串))

curl 示例

BODY='{"requestedAmount":"50.00","requestedCurrency":"USD","reference":"ORDER-1001"}'
TS=$(date +%s); NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIG=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" "$NONCE" POST /v1/orders "$BODY_HASH" \
  | openssl dgst -sha256 -hmac "$BESO_API_SECRET" -hex | sed 's/^.* //')

curl -X POST https://api.peer.besofinance.xyz/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $BESO_API_KEY" -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" -H "X-Signature: $SIG" \
  -d "$BODY"

Python 示例

import hashlib, hmac, json, os, secrets, time, urllib.request

def beso(method, path, body=None):
    raw = json.dumps(body, separators=(",", ":")) if body is not None else ""
    ts, nonce = str(int(time.time())), secrets.token_hex(16)
    msg = "\n".join([ts, nonce, method, path, hashlib.sha256(raw.encode()).hexdigest()])
    sig = hmac.new(os.environ["BESO_API_SECRET"].encode(), msg.encode(), hashlib.sha256).hexdigest()
    req = urllib.request.Request("https://api.peer.besofinance.xyz" + path, data=raw.encode() or None, method=method,
        headers={"X-API-Key": os.environ["BESO_API_KEY"], "X-Timestamp": ts, "X-Nonce": nonce,
                 "X-Signature": sig, "Content-Type": "application/json"})
    return json.load(urllib.request.urlopen(req))

beso("POST", "/v1/orders", {"requestedAmount": "50.00", "requestedCurrency": "USD", "reference": "ORDER-1001"})

密钥轮换与吊销

• 轮换:后台“开发者”页点“轮换”,立即生成新密钥;旧密钥在宽限期内继续有效(默认 24 小时,可选 0–168 小时),到期后返回 401 API_KEY_EXPIRED。
• 吊销:立即失效,之后的请求返回 401 API_KEY_REVOKED。怀疑泄露时请直接吊销。

IP 白名单(可选)

在后台“开发者 → IP 白名单”为每个环境设置允许调用的公网 IPv4 / IPv6 地址或 CIDR 段(IPv4 前缀 /8–/32,IPv6 /32–/128,最多 50 条;单个地址按 /32 或 /128 保存)。空列表表示不限制。白名单只约束 API 密钥调用,不影响商家后台登录。不在名单内的请求返回:

{
  "success": false,
  "message": "IP address 203.0.114.7 is not in this merchant's API key IP allowlist",
  "responseObject": { "ip": "203.0.114.7", "reason": "IP_NOT_ALLOWED" },
  "statusCode": 403,
  "errorCode": "IP_NOT_ALLOWED"
}

无法确定来源 IP 时 reason 为 CLIENT_IP_UNRESOLVED(状态码与 errorCode 相同)。

旧版单一密钥

早期发放的 beso_sk_… 单一密钥(只放 X-API-Key,不签名)在过渡期内继续可用,作用于部署时的默认环境。被平台关闭后返回 401 LEGACY_KEY_DISABLED,请在后台改用公钥 + 私钥。

免密钥接口

GET /v1/orders/{orderId} 无需密钥(订单 ID 本身即凭证),供结账页读取订单;POST /v1/onboarding/applications 用于提交开户申请。

API 参考 · 基础约定

基础地址(沙盒与正式相同,环境由密钥决定):

https://api.peer.besofinance.xyz/v1

统一响应格式

{
  "success": true,
  "message": "Merchant orders retrieved",
  "responseObject": { ... },
  "statusCode": 200
}

参数校验失败返回 400、errorCode: "VALIDATION_ERROR",具体字段错误在 responseObject.fieldErrors(对象:字段名 → 错误数组),整体错误在 responseObject.formErrors。

数据格式

• 时间:ISO 8601 UTC,如 2026-10-06T10:15:42.318Z。
• 金额:十进制字符串,不使用浮点数,如 "25"、"23.14"。末尾的 0 不保证保留,请解析后再比较。
• 链 ID:响应里是十进制字符串(如 "8453");请求里数字或字符串都可以。
• ID:订单 ord_…、Webhook wh_…、投递 dlv_…、退款申请 rfr_…、事件 evt_…;支付 ID 沿用支付网络的 ID。

API 参考 · 接口列表

路径相对于 https://api.peer.besofinance.xyz。“密钥”= 签名的 API 密钥;“停用时”= 订阅停用(402)期间是否仍可调用。

商家后台使用同一套接口(路径前缀为 /portal,登录会话鉴权),另有 API 密钥管理与 IP 白名单设置,只能在后台操作。

API 参考 · 创建订单

POST https://api.peer.besofinance.xyz/v1/orders

请求字段

金额二选一:requestedAmount + requestedCurrency(按法币报价),或 requestedUsdcAmount(按 USDC 报价)。

金额限制

• 每单折合 USDC 须在支付网络的最小额(默认 10 USDC,沙盒同样适用)与 10,000 USDC 之间,否则返回 400 AMOUNT_BELOW_MIN / AMOUNT_ABOVE_MAX;每笔钱包付款含手续费也不能超过 10,000 USDC:买家承担手续费(PAYEE)的大额订单,超出部分的钱包会显示为不可用,买家发起付款时返回 INTENT_ABOVE_MAX(建单时不会返回)。超过上限的购买请拆成多张订单。
• 暂不支持开放金额订单(买家自填金额,openAmount),传入会返回 400。

幂等与重放

同一环境内用同一个 reference 再次创建,返回 200 和原订单,并带 idempotentReplay: true,不会重复建单;但如果金额、币种或金额模式与原订单不同,返回 409 IDEMPOTENCY_KEY_CONFLICT。首次请求返回 201。如果首次请求在支付网络已建单但链接未能保存(极少见),返回 409 CHECKOUT_URL_UNRECOVERABLE,请换一个 reference 重建。

响应(订单对象)

{
  "id": "ord_2b9c…",
  "environment": "SANDBOX",
  "status": "CREATED",
  "amountMode": "FIXED",
  "requestedAmount": "50.00", "requestedCurrency": "USD",
  "requestedUsdcAmount": "50", "remainingUsdcAmount": "50",
  "netSettledUsdcAmount": null, "fulfillTransaction": null,
  "destinationAddress": "0x…", "destinationChainId": "8453", "destinationToken": "USDC",
  "checkoutUrl": "https://pay.peer.xyz/checkout?…",
  "chargebackStatus": "NONE", "refundStatus": "NONE", "settledPaymentCount": 0,
  "notes": { "customerId": "C-88" },
  "reference": "ORDER-1001",
  "lastEvent": null,
  "createdAt": "2026-10-06T10:15:42.000Z", "updatedAt": "2026-10-06T10:15:42.000Z"
}

上述上游字段取自最近一次同步的支付网络快照;刚建单、尚未同步时可能为 null。上游的子账户 ID、分成配置与分成明细等内部字段不会返回。

API 参考 · 订单、支付与商家

支付对象

由 /merchants/me/orders/{orderId}/payments、/merchants/me/payments 和 Webhook 的 data.payment 返回:

订单列表 GET /v1/merchants/me/orders

按创建时间倒序;page(默认 1)、limit(默认 20,最大 100,超过返回 400 而不是截断)。返回 { orders, total, page, limit }(旧字段 rows 与 orders 相同,保留兼容)。

列表中的每个订单比单笔查询多 5 个由支付记录推导的字段:hasActivePayment、hasExpiredPayment、paymentSelectedRail(进行中尝试的通道,否则最近一次过期尝试的通道)、settledPaymentCount、settledPaymentRails(按支付创建时间去重)。

商家资料 GET /v1/merchants/me

用量 GET /v1/merchants/me/usage

返回近 30 天(当前环境)的 orders、fulfilledOrders、settledUsdc、successRate(%)和订阅对象。订阅本身不限笔数和金额,cap 恒为 null。

套餐额度 GET /v1/merchants/me/tier-usage

原样透传上游 Peer 的同名接口:{ tier, limits, usage, windowStart, windowEnd }。limits(volumeUsdc、orderCount)为 null 表示没有上限(本平台目前的上游账户与沙盒均为 null);usage 统计本自然月(UTC)创建、且至少有一笔法币支付结算的已完成 / 部分完成订单,按订单的请求 USDC 金额累计。上游不会在接近上限时发通知,建议自行定时查询;达到上限后创建订单会返回 403 MERCHANT_MONTHLY_VOLUME_LIMIT_EXCEEDED 或 MERCHANT_MONTHLY_ORDER_LIMIT_EXCEEDED。

额度检查 POST /v1/merchants/me/quotes/availability

收款目的地自动使用你的默认钱包。返回支付网络的可用性结果(是否可成交,以及附近金额建议)。

接入自检 GET /v1/integration/status

返回 environment、authMode(signed / legacy)、subscription(状态)、webhooks(启用的端点数)、lastWebhookDelivery、lastOrderAt、ready(订阅有效且至少有一个 Webhook)。另有与 Peer 同名的接入清单字段:verified(你的接口已成功接收过一次签名的沙盒投递;判断是否接好请看它)、liveWebhookReady、complete(已有正式订单)、steps(每步含 id、actor、done、evidence;actor 为 MERCHANT 的步骤需在商家后台完成,BESOFINANCE 的由我们开通)和 nextAction(下一个未完成步骤)。

API 参考 · 限流与分页

限流

• 每把 API 密钥每分钟 600 次请求(平台可调整)。
• 测试类接口:Webhook 测试每 10 分钟 5 次(与 Peer 相同),沙盒测试单每分钟 5 次;开户申请每个 IP 每分钟 10 次。
• 补救接口另受支付网络限制:每个商户每分钟 30 次操作、120 次读取。

每个响应带 x-rate-limit-remaining。超限返回 429 RATE_LIMITED,响应头含 x-retry-after(多少秒后可重试,同时提供标准 Retry-After)与 x-rate-limiter-resets-at(ISO 时间)。

分页

列表响应为 { <列表名>, total, page, limit },按创建时间倒序:订单列表是 orders,支付列表是 payments,投递日志是 deliveries,退款申请是 refundRequests。订单列表另带一个与 orders 相同的 rows 字段,仅为兼容旧接入,新代码请读 orders。

API 参考 · 支付补救

买家付款遇到问题时(尝试过期但其实已付款、需要更多时间、已付款但没完成验证),可以用补救接口处理。仅正式环境,沙盒返回 403 SANDBOX_NOT_SUPPORTED;只适用于法币通道。paymentId 来自 GET /v1/merchants/me/orders/{orderId}/payments。

请求体都可带 idempotencyKey(8–200 位),同一个键重试返回同一个动作。成功返回 202 与动作对象:

{
  "actionId": "…", "actionName": "RECREATE", "paymentId": "…", "orderId": "ord_…",
  "status": "QUEUED",      // PENDING_APPROVAL / QUEUED / RUNNING / SUCCEEDED / BLOCKED / FAILED
  "error": null, "result": null, "payment": { … }, "createdAt": "…", "startedAt": null, "finishedAt": null
}

用 GET /v1/merchants/me/orders/{orderId}/actions/{actionId} 轮询结果。不满足条件返回 422,responseObject.reason 给出原因(如 PAYMENT_STATUS_NOT_ELIGIBLE、RAIL_NOT_SUPPORTED、EXTEND_TOO_EARLY、SAR_NOT_AVAILABLE);同类动作进行中返回 409 ACTION_IN_PROGRESS(带 actionId);功能关闭时 503 FEATURE_DISABLED。错误码同时出现在 errorCode 与 responseObject.code。

API 参考 · 退款申请

退款由 Besofinance 审核后代为执行,全额退回买家原付款账户。你通过 API 或后台“退款”页提交申请,状态变化会以 REFUND_REQUEST_UPDATED 事件通知你;支付网络完成退款时另有 REFUND_PENDING / REFUND_COMPLETED 事件。

可退款条件

• 正式环境订单,状态为 FULFILLED,且恰好有一笔已结算支付;
• 付款通道为 Venmo、Cash App、PayPal、Zelle、Revolut、Wise 或 Monzo(Chime、N26、数字货币、Apple Pay 不支持);
• 结算到 Base 网络的 USDC;没有拒付记录,也没有进行中或已完成的退款;
• 买家付款币种需在支持范围内(包括 USD、EUR、GBP);只支持全额退款:买家拿回原付款平台上、原币种的全部付款金额。
• 退款以 USDC 报价发出,为了尽快成交,所需 USDC 通常比按市场汇率折算多约 1%;原交易的手续费不退还。退款资金的结算方式以商务协议为准。

提交申请

POST /v1/refund-requests
{ "orderId": "ord_…", "refundTo": "@buyer-venmo", "reason": "客户取消" }

返回 201 与退款申请对象:id、orderId、environment、status、type(恒为 FULL)、reason、refundTo、rail、amount、currency、adminNote、peerRefundStatus、refundTransactionHash、createdAt、updatedAt。

错误:传 amount 返回 400 PARTIAL_REFUND_NOT_SUPPORTED;已有进行中的申请返回 409 REFUND_ALREADY_REQUESTED;不满足条件返回 422 REFUND_NOT_ELIGIBLE,responseObject.reason 为 SANDBOX_NOT_SUPPORTED、ORDER_NOT_FULFILLED、ALREADY_REFUNDED、CHARGEBACK_RECORDED、MULTIPLE_OR_NO_SETTLED_PAYMENTS、RAIL_NOT_REFUNDABLE 或 PAYOUT_NOT_BASE_USDC。

状态

API 参考 · 订阅与账单

GET /v1/merchants/me/subscription

{
  "subscription": {
    "plan": "merchant", "monthlyFee": "1000", "currency": "USD",
    "activatedAt": "2026-10-01", "paidThrough": "2026-10-31", "currentPeriodEnd": "2026-10-31",
    "nextChargeDate": "2026-11-01", "cutoffDate": "2026-11-03", "graceDays": 3,
    "status": "active"     // active / past_due / suspended / cancelled / not_started
  },
  "invoices": [ { "id": "inv_…", "periodStart": …, "periodEnd": …, "amount": "1000.00", "currency": "USD",
                   "months": 1, "method": "peer", "status": "open", "checkoutUrl": "https://…", "paidAt": null } ]
}

POST /v1/merchants/me/subscription/invoices

请求体 { "months": 1 }(1–12)。已有未付账单时直接返回它;否则生成新账单并返回带 checkoutUrl 的账单对象。账单在结账页付款结算后自动入账,订阅立即顺延,并发送 SUBSCRIPTION_PAID / SUBSCRIPTION_ACTIVE 事件。

API 参考 · 沙盒测试单

POST /v1/sandbox/test-order
{ "amount": "10.00", "currency": "USD", "rail": "venmo" }

只能用沙盒密钥(正式密钥返回 403 SANDBOX_ONLY),每分钟最多 5 次。不动真钱。

Webhooks · 创建与管理

Webhook 以带签名的 POST 请求,把订单、支付、退款和订阅的状态变化推送到你的服务器,每次都附带订单与支付的完整快照。Webhook 按环境注册:用沙盒密钥注册的端点只收沙盒事件,用正式密钥注册的只收正式事件,各有自己的签名密钥。

基本流程

1. 创建 Webhook 并妥善保存签名密钥(只显示一次)。
2. 订阅需要的事件。
3. 每次收到请求都验证签名与时间戳。
4. 用 X-Webhook-Id 去重,避免重复处理。
5. 用 data.order.id / data.order.reference 和 data.payment.id 与你自己的订单对账。

创建

POST https://api.peer.besofinance.xyz/v1/webhooks
{
  "url": "https://yoursite.com/webhooks/beso",
  "events": ["ORDER_FULFILLED", "PAYMENT_SETTLED", "REFUND_REQUEST_UPDATED"],
  "customHeaders": [{ "key": "X-Auth", "value": "Bearer 共享口令" }]
}

返回 201:{ id, url, events, environment, active, customHeaders, secret },其中 secret(whsec_…)仅显示一次。

你的接口需要做到

• 接收带 JSON 的 POST 请求。
• 先验证签名,再处理数据。
• 30 秒内返回 2xx,耗时的处理放到异步。重定向(3xx)视为失败。

重试策略

首次投递失败后按下表重试,最多共 7 次尝试(约 35 小时):

7 次都失败后标记为 FAILED,不再自动重试,但你可以随时手动重发。投递状态:PENDING(待投递或待重试)、DELIVERED(收到 2xx)、FAILED(次数用尽或端点已删除 / 停用)。重试队列持久化保存,服务重启不会丢失。

管理接口

# 列表(当前环境)
GET    /v1/webhooks

# 更新:url / events / active / customHeaders(customHeaders 整体替换,传 [] 清空)
PATCH  /v1/webhooks/{webhookId}      { "active": false }

# 轮换签名密钥:返回新 secret(只显示一次),旧 secret 立即失效
POST   /v1/webhooks/{webhookId}/rotate-secret

# 删除
DELETE /v1/webhooks/{webhookId}

# 发送测试事件:只发给这个端点,类型为 ORDER_CREATED,data.test = true,快照均为 null;只尝试一次、不重试(每 10 分钟最多 5 次)
# 返回 { success, deliveryId, responseCode, error }
POST   /v1/webhooks/{webhookId}/test

# 该端点最近 50 次投递
GET    /v1/webhooks/{webhookId}/deliveries

Webhooks · 事件与负载

负载结构

{
  "id": "evt_…",                 // 同 X-Webhook-Id,用来去重
  "type": "ORDER_FULFILLED",
  "environment": "LIVE",          // SANDBOX / LIVE;订阅类事件为 null
  "timestamp": "2026-10-06T10:20:03.112Z",
  "data": {
    "order": { … },               // 订单对象(同“创建订单”的响应)
    "payment": { … } | null,       // 支付对象
    "refund": { … } | null,        // 退款事件
    "paymentBridge": { … } | null  // 桥接事件
    // 仅特定事件:trigger(拒付)、resize(ORDER_RESIZED)、amountChange(ORDER_AMOUNT_SET)
  }
}

订单与支付事件

Besofinance 平台事件

订阅类事件与环境无关(environment 为 null),会投递到两个环境中订阅了该事件的端点。

Webhooks · 验签

请求头

算法

signature = hex(HMAC-SHA256(secret, timestamp + "." + rawBody))

时间戳与当前时间相差超过 5 分钟(300 秒)的请求应当拒绝。

Node.js 示例

const crypto = require('crypto');

function verify(rawBody, headers, secret) {
  const ts  = headers['x-webhook-timestamp'];
  const sig = headers['x-webhook-signature'] || '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(ts + '.' + rawBody)
    .digest('hex');

  const a = Buffer.from(sig, 'hex'), b = Buffer.from(expected, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);   // 长度不同时 timingSafeEqual 会抛异常,先比长度
}

使用 SDK 时直接调用 verifyWebhook(rawBody, req.headers, process.env.BESO_WEBHOOK_SECRET)。Express 中请用 express.raw({ type: 'application/json' }) 拿到原始请求体。

Python 示例

import hmac, hashlib, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts, sig = headers.get("X-Webhook-Timestamp", ""), headers.get("X-Webhook-Signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

处理清单

• 每次都验证签名与时间戳,超过 5 分钟的一律拒绝。
• 使用防时序攻击的比较函数,不要直接用 ==。
• 先验证原始请求体,再解析 JSON。
• 先返回 2xx,再异步处理。
• 用 X-Webhook-Id 作为幂等键去重(重试与手动重发的 ID 相同)。
• 只在收到 ORDER_FULFILLED(或 data.order.status 为 FULFILLED)后发货。
• 先核对 environment:正式店铺只处理 LIVE 事件。
• 记录事件 ID、类型和订单 ID。
• 签名密钥放在环境变量中,不要写进日志或分享给他人。

Webhooks · 投递日志与重发

每次投递都会记录:状态、尝试次数、每次尝试的 HTTP 状态码 / 错误 / 耗时、下次重试时间和原始负载。商家后台“开发者 → 投递日志”可查看并一键重发。

# 列表(分页;可按 status=PENDING|DELIVERED|FAILED、type=事件名 过滤)
GET  /v1/webhook-deliveries?status=FAILED&limit=50

# 详情:含 attemptLog(每次尝试)与 payload(原始负载)
GET  /v1/webhook-deliveries/{deliveryId}

# 手动重发:任何状态都可以(包括 DELIVERED),事件 ID 不变,签名用新的时间戳
POST /v1/webhook-deliveries/{deliveryId}/resend

投递对象字段:id、webhookId、eventId、type、environment、status、attempts、lastStatusCode、lastError、nextAttemptAt、deliveredAt、createdAt、updatedAt。手动重发不占用自动重试次数。

参考 · 订单与支付状态

订单代表需要收取的总金额;支付代表买家在某个钱包上的一次付款尝试。一张订单可以有多次支付尝试。

订单状态

拒付(chargebackStatus)和退款(refundStatus)单独记录,不会改变订单的 status:被拒付或已退款的订单仍是 FULFILLED。

支付状态

付款时限

状态流转

• 买家选择钱包 → 支付 CREATED
• CREATED → SETTLED(结算确认)/ EXPIRED / FAILED / CANCELLED
• EXPIRED / FAILED / CANCELLED 可通过补救接口 recreate 重新打开为 CREATED
• EXPIRED / CANCELLED 遇到迟到的结算可转为 SETTLED
• 支付 SETTLED 后订单变为 PARTIALLY_FULFILLED 或 FULFILLED

参考 · 支持的法币钱包

报价支持以下 33 种法币(某张订单实际能用哪些,取决于启用的钱包和当时的流动性;没有流动性的钱包在结账页显示为不可用):

AED  ARS  AUD  CAD  CHF  CNY  CZK  DKK  EUR  GBP  HKD
HUF  IDR  ILS  INR  JPY  KES  MXN  MYR  NOK  NZD  PHP
PLN  RON  SAR  SEK  SGD  THB  TRY  UGX  USD  VND  ZAR

每笔支付记录报价所用的汇率 currencyPerUsdRate。

使用 Zelle 时,买家会选择自己的银行(例如 zelle-chase、zelle-bofa、zelle-citi),对应支付对象里的 paymentMethodId 字段;其他钱包该字段为 null。Zelle 与 N26 的买家验证需要桌面浏览器扩展。

参考 · 支持的数字货币

结账页除法币钱包外,还提供数字货币付款通道。默认收款目的地为 Base 网络上的 USDC;收款目的地由订单的 destinationChainId 与 destinationToken(即请求里的 settleChain / settleToken)单独设置。

买家如何用数字货币付款

1. 买家选择一条链。
2. 买家从该网络上的钱包完成转账。
3. 转账被桥接到你的收款目的地,过程中会收到 PAYMENT_BRIDGE_* 事件。

数字货币通道标识

在建单请求的 enabledRails 中使用,格式为 relay_<chainId>,每条受支持的买家付款链对应一个;另有 Zcash 与 Apple Pay 两个标识。旧写法 crypto_<chainId> 仍被接受并自动转换。

买家可用的数字货币(以结账页实际显示为准)

网络:Bitcoin、Ethereum、Solana、Base、Optimism、BNB Smart Chain、Polygon、World Chain、Hyperliquid、Arc、Arbitrum、Zcash、Tron。

订单里与数字货币有关的字段

默认收款钱包是开户时登记的 EVM 地址(evmWalletAddress);结算到 Solana、Tron 等非 EVM 网络时,请在建单时传入对应网络的 settleAddress。

手续费承担方

通过 feePayer 设置:MERCHANT(商家承担)、PAYEE(买家承担)、SPLIT(分摊);SPLIT 时用 buyerFeeShareBps(0–10000,1000 的倍数)设置买家分摊的比例。

参考 · 错误码

请按 errorCode 做程序判断,message 只用于日志。支付网络返回的业务错误码会原样透传。

参考 · 与 Peer 原生 API 的差异

如果你之前直接对接过 Peer Pay(api.pay.peer.xyz),迁移到本 API 时注意以下差异:

联系我们

接入、费率、退款或合作问题,请发邮件至 xiongfei@besofinance.xyz。