API 参考

面向商户的 REST API 精选参考。所有端点位于 https://api.faststarpay.com/api/v1 下，并返回统一的 { success, message, data } 响应包。

认证与约定

在商户后台创建 API Key，并在每个请求中以 X-API-Key 请求头携带。Key 只保存在服务端。
请求与响应均为 JSON（Content-Type: application/json）。
金额一律为最小货币单位的整数（如 999 = 9.99 美元）。
成功响应形如 { "success": true, "message": "...", "data": { ... } }；失败时 "success": false 并附带说明性 message。

curl https://api.faststarpay.com/api/v1/public/checkout/sessions \
  -H "X-API-Key: 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Checkout Session

端点	方法	说明
`/public/checkout/sessions`	POST	创建会话（`payment` \| `subscription` \| `setup`），返回托管收银台 `url`
`/public/checkout/sessions/:id`	GET	查询会话（状态、金额）

curl https://api.faststarpay.com/api/v1/public/checkout/sessions \
  -H "X-API-Key: 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "presentation": "iframe",
    "line_items": [{ "price_id": "price_xxx", "quantity": 1 }],
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel"
  }'

完整字段与响应结构见 Checkout Session 指南。注意：MoR 商户的每个 line item 必须引用商品目录的 price_id/product_id。

商品目录（Products & Prices）

端点	方法	说明
`/merchant/catalog/products`	POST	创建商品（`name` 必填；可选 `description`、`tax_category`、`images`、`metadata`）
`/merchant/catalog/products`	GET	商品列表
`/merchant/catalog/prices`	POST	为商品创建价格
`/merchant/catalog/prices`	GET	价格列表

价格字段：product_id、currency 与 unit_amount（最小货币单位）必填；type 为 one_time 或 recurring，recurring 价格需要 recurring_interval（另有可选的 recurring_interval_count 与 trial_period_days）。

curl https://api.faststarpay.com/api/v1/merchant/catalog/prices \
  -H "X-API-Key: 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xxx",
    "currency": "USD",
    "unit_amount": 1900,
    "type": "recurring",
    "recurring_interval": "month"
  }'

Customers 与支付方式

端点	方法	说明
`/public/customers`	POST	创建客户（`email` 必填）
`/public/customers`	GET	客户列表
`/public/customers/:id`	GET	查询客户
`/public/customers/:id/setup-intent`	POST	创建用于加卡的 SetupIntent → `{ client_secret, publishable_key, setup_intent_id }`
`/public/customers/:id/payment-methods`	POST	用完成的 SetupIntent 绑定卡片（`{ setup_intent_id }`）→ 脱敏卡 `{ id: "pm_…", brand, last4, exp_month, exp_year }`
`/public/customers/:id/payment-methods`	GET	列出客户已存卡（脱敏）
`/public/customers/:id/charge`	POST	对已存卡 off-session 扣款；需要 SCA 时返回 HTTP 402
`/public/payment-methods/:id/default`	POST	把某张已存卡设为客户默认卡
`/public/payment-methods/:id`	DELETE	解绑已存卡

curl -X POST https://api.faststarpay.com/api/v1/public/customers/cus_xxx/charge \
  -H "X-API-Key: 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_id": "pm_xxx", "amount": 1999, "currency": "USD", "off_session": true }'

端到端流程见保存卡指南。

税额

端点	方法	说明
`/public/tax/calculate`	POST	按金额与买家所在地试算税额（MoR）

curl https://api.faststarpay.com/api/v1/public/tax/calculate \
  -H "X-API-Key: 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1000, "country": "DE" }'

响应 data：

{
  "country": "DE",
  "tax_type": "vat",
  "rate_percent": 19,
  "inclusive": true,
  "tax_amount": 160,
  "net_amount": 840,
  "gross_amount": 1000
}

Webhook 验签

端点	方法	说明
`/public/verify-signature`	POST	验证 Webhook 签名（`{ provider_name, payload, signature }` → `{ valid }`）

推荐在本地用 HMAC 验证商户 Webhook 签名——见 Webhook 指南。

错误

错误使用常规 HTTP 状态码，并配合响应包（"success": false + 可读的 message）：

状态码	含义	常见原因
`400`	请求有误	字段缺失或非法（如缺少 `line_items`、MoR line item 未引用商品目录）
`401`	未认证	`X-API-Key` 缺失或无效
`402`	需要支付验证	off-session 扣款需要强客户认证——改走 on-session 流程
`404`	未找到	id 不存在（客户、会话、价格等）
`5xx`	服务端错误	瞬时故障——退避重试

{ "success": false, "message": "Payment requires additional authentication" }