集成文档

概览

101pay API 是一个 JSON REST API。所有请求与响应均使用 application/json. 基础 URL：

https://api-production-4983.up.railway.app

认证

API 根据不同端点接受三种凭证类型：

1 · API 密钥对 —— 用于 Charge API

一个公钥（pk_test_…）和一个私钥（sk_test_…），在密钥管理中生成。只有当两个密钥构成匹配的密钥对时，交易才会结算。密钥对在请求体中传递。

2 · 会话令牌（JWT）—— 用于账户与管理端点

从以下端点获取令牌 POST /v1/auth/login 并以 Authorization: Bearer <token> 发送。用于创建收银台会话、密钥管理、交易账单、KYC 与支付方式。

3 · 商户 API 密钥 —— 用于 x402 支付历史

注册时仅显示一次（ap_test_…）。以 Authorization: Bearer <apiKey> 发送至 GET /v1/payments.

快速开始

• 1 —— 在控制台创建账户（或 POST /v1/auth/register）。
• 2 —— 打开密钥管理并生成一个密钥对。请保存私钥。
• 3 —— 使用 Charge API（见下文）结算你的第一笔交易。

Charge API

用密钥对结算一笔交易。无需请求头认证 —— 密钥对在请求体中传递。

请求体

• publicKey —— 字符串，必填
• privateKey —— 字符串，必填
• amount —— 小数字符串，必填（例如 "9.99"）
• currency —— USDC · USDT · JPY · USD （默认 USDC）
• description —— 字符串，可选

curl -X POST https://api-production-4983.up.railway.app/v1/transactions/charge \
  -H "content-type: application/json" \
  -d '{
    "publicKey":  "pk_test_…",
    "privateKey": "sk_test_…",
    "amount":     "9.99",
    "currency":   "USD",
    "description":"order #1024"
  }'

响应 200

{
  "orderNo":     "20260517000000042",
  "transaction": "0x…",
  "amount":      "999",
  "currency":    "USD",
  "status":      "settled"
}

不匹配的密钥对会返回 401 key_pair_invalid。 amount 以最小单位回显（见参考）。

托管收银台

创建一个收银台会话，然后将客户引导至托管的 url。客户选择一种加密支付方式（USDC、BTC、ETH、…），并在托管页面上通过 requires_action → confirm 流程付款。

curl -X POST https://api-production-4983.up.railway.app/v1/checkout/sessions \
  -H "authorization: Bearer <JWT>" \
  -H "content-type: application/json" \
  -d '{ "amount":"1500", "currency":"JPY", "description":"Pro plan" }'

# → { "session": { "id": "…", "status": "open", … }, "url": "https://…/checkout/<id>" }

在生产环境中，confirm 步骤由支付服务商的 Webhook 驱动；托管页面会为你处理。

USDT 支付

在 TRON 网络（TRC20）上收 USDT。平台非托管 —— 资金直接结算进你自己的收款地址。

1 · 配置收款账号

在后台打开「收款账号」，添加你的 USDT-TRC20 地址。你账户的每笔 USDT 支付都结算到这里。

2 · 发起支付

你的服务端用 Client ID 和一个密钥（Keys 页里的某个私钥）调用下面的接口。不配对返回 401。

请求体

• clientId 你的 15 位 Client ID
• secret 密钥对的私钥 (sk_test_…)
• amount 十进制字符串，如 "1.00"
• currency 计价币种 —— USDC · USDT
• method 支付方式 —— usdt

curl -X POST https://api-production-4983.up.railway.app/v1/payments \
  -H "content-type: application/json" \
  -d '{
    "clientId": "101000000000000",
    "secret":   "sk_test_…",
    "amount":   "1.00",
    "currency": "USDT",
    "method":   "usdt"
  }'

响应

响应返回 cryptoPayLink —— 把客户引导到这个收银台链接去付款。

{
  "success": true,
  "payment": { "id": "…", "status": "open", "amount": "1.00", "currency": "USDT", "method": "usdt" },
  "cryptoPayLink": "https://…/en/checkout/<id>"
}

3 · 客户付款

客户打开 cryptoPayLink，选择 USDT，看到你的收款地址和精确应付金额。链上转账经 TronGrid 确认后，订单标记为已支付。

金额带一个唯一的不到一分的尾数，以便每笔支付能在链上被匹配。客户必须转一分不差的金额，并保持收银台页面打开直到确认。

Agentic 支付（x402）

用 x402 协议为任意资源定价，使 AI agent 可按请求付费。

若无 X-PAYMENT 请求头，端点会返回带 PaymentRequirements 的 402。Agent 签署一份 EIP-3009 授权，并带上 X-PAYMENT 请求头重试；facilitator 验证并结算，随后返回资源。支付历史： GET /v1/payments （商户 API 密钥）。

参考

币种

• USDC —— 6 位小数 · USD —— 2 位小数 · JPY —— 0 位小数
• 响应中的金额为整数最小单位（例如 USD “999” = $9.99，JPY “1500” = ¥1500）。

支付方式

• usdc · btc · eth · usdt · bnb · sol · ada · xrp · doge · dot
• 所有方式均为加密轨道 —— 客户向充值地址付款。

订单号

每笔交易都会获得一个唯一的 17 位订单号：交易日期的 8 位（YYYYMMDD）+ 9 位序列 —— 例如 20260517000000042。

错误

错误会返回一个 JSON 响应体和对应的 HTTP 状态：

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

• 400 invalid_request · 401 unauthorized · 402 payment_rejected
• 404 not_found · 409 conflict · 500 internal_error