101pay 文档

商户注册和开始使用

先完成账户、邮箱验证和控制台访问。生产环境正式收款前，需要完成对应 KYC 和合作方配置。

• 从公开页面注册，验证邮箱后登录商户控制台。
• 在 Key management 生成支付 key pair，private key 只应保存在服务端。
• 通过控制台查看交易、平台绑定、资金记录和账户安全。
• 如果从 Fluere SSO 进入，建议在 Account security 设置 101pay 密码，后续可以直接管理 101pay。

认证和 API Key

101pay 在不同场景使用不同凭证。不要把 checkout key、用户 session 和 Staff 凭证混用。

• Key pair：public key + private key，用于服务端 charge 请求。
• Session token：登录后获得的 JWT，用于商户管理接口。
• Merchant API key：部分 x402 和支付历史接口使用的 bearer key。
• Staff 和 reviewer 路由需要对应角色登录，不能用商户凭证访问。

curl -X POST https://pay101-api-5qjldqffdq-uw.a.run.app/v1/auth/login \
  -H "content-type: application/json" \
  -d '{"email":"merchant@example.com","password":"***"}'

Checkout 和支付会话

Hosted checkout 创建支付会话并返回 URL。客户在托管页面完成支付，101pay 记录 provider 状态和结算证据。

• 创建 session 时传入金额、币种、描述和可选业务元数据。
• 把 hosted checkout URL 发给客户，或嵌入自己的付款流程。
• 托管页面负责支付方式选择、付款指令、确认和状态轮询。
• 生产环境确认应依赖 provider/webhook 证据，而不是人工假设页面已完成。

curl -X POST https://pay101-api-5qjldqffdq-uw.a.run.app/v1/checkout/sessions \
  -H "authorization: Bearer <JWT>" \
  -H "content-type: application/json" \
  -d '{"amount":"1500","currency":"USD","description":"Pro plan"}'

x402 Agent 支付

x402 让 API 可以用 HTTP 402 给资源标价。Agent 签名付款授权后，带 X-PAYMENT 重试同一个资源请求。

• 没有 X-PAYMENT 的资源请求返回 402 Payment Required 和付款要求。
• Agent 在自己的策略和预算内签名付款 payload。
• 101pay 通过 facilitator 验证并结算，然后返回付费资源。
• 商户可用支付历史按资源、客户和请求维度对账 agent 消费。

curl https://pay101-api-5qjldqffdq-uw.a.run.app/v1/resource/<sku>?merchant=<merchantId>
# 402 Payment Required -> agent signs -> retry with X-PAYMENT

Fluere 绑定和 CRD 资金闭环

Fluere 可以绑定 101pay 账户，用于购买 CRD、提现 CRD，并在 101pay 侧追踪 payout 执行。

• 已绑定 Fluere 的 101pay 账户会在 dashboard 展示 platform binding 信息。
• CRD purchase order 会占用 101pay 资金余额，并把状态回写给 Fluere。
• CRD withdrawal order 从 Fluere 发起，101pay 负责保存出款目的地和执行状态。
• 未绑定账户不展示 Fluere 专属资金面板，并引导客户查看 platform bindings。

资金钱包和充值入账

钱包记录用于充值匹配和出款记录。

• 输入有效的 EVM 地址后即可保存到当前 101pay 账户。
• 充值匹配会检查链、来源钱包、收款账户、金额、交易哈希和确认状态。
• 如果客户先转账后保存钱包，保存同一个来源地址后，系统可以尝试认领符合条件的 pending deposit。

提现和出款模式

101pay 记录 CRD 提现的 payout 执行状态，Fluere 仍是 CRD 账本事实来源。

• 当前默认 CRD 提现目的地是已启用的 USD bank account。
• USDC wallet 记录保留给钱包出款 fallback 和审计历史。
• Coinbase Business 出款由 Staff 操作：打开转账、外部完成转账，再记录 tx 或 payout 证据。
• Manual off-platform payout 默认只作为禁用历史展示，除非 Staff 明确做例外处理。

Staff 和 Reviewer 操作

运营人员处理 KYC、资金异常、Treasury 账户、CRD 购买单、提现单、充值、出款批次和账本证据。

• Reviewer 路由主要处理 KYC 审核和合作方传输状态。
• Staff Funding 展示 Fluere 绑定账户、wallet account、CRD purchase/withdrawal order、deposit、payout batch 和 ledger。
• Treasury 页面用于管理公开收款账户和充值匹配需要的运营信息。
• 所有人工流转都应留下状态、备注、操作人、时间和幂等证据。

接口参考和错误

所有 API 响应使用 JSON。错误响应尽量带稳定 error code，方便商户和 Agent 按规则恢复。

• 常见状态：400 invalid_request、401 unauthorized、402 payment_required/payment_rejected、404 not_found、409 conflict、500 internal_error。
• 响应中的金额使用 minor units。USDC 是 6 位小数，USD 是 2 位小数，JPY 是 0 位小数。
• purchase、withdrawal、payout 和 ledger 等重试敏感操作应使用 idempotency key 或稳定业务引用。
• 生产和测试环境的 OTP、provider mock、结算通道可能不同。测试资金前先确认目标环境。

{ "error": "key_pair_invalid", "message": "the public key and private key do not form a valid pair" }