用 Checkout 收款

买家需要一次性付清一笔固定金额时（下单、付账单、充值单等），用 Checkout 最合适。

流程很直接：你的服务端创建 Checkout Session → 买家在 Hosted 收银台（pay.doggiepay.com）或通过 Button SDK 付款 → 你收到 webhook checkout.paid（也可以再用服务端查单核对）→ 把订单标为已支付，然后发货或开通权益。

开始前请先读完 快速开始，准备好 Secret Key 和 Request-Id。

你的服务端                 Doggie Pay                  买家
    |                           |                       |
    |-- POST /checkout/sessions -->|                       |
    |<-- hosted_url, id -----------|                       |
    |-- 打开 hosted_url ---------->|---------------------->|
    |                           |<-- 链上 USDC/USDT ------|
    |<-- webhook checkout.paid ----|                       |
    |-- 标已付 → 发货 / 开通权益 ---|                       |

1. 创建 Checkout Session

POST /v1/checkout/sessions
鉴权： Secret 或 Publishable 都可以，但都必须带 Request-Id。

请求体

请求示例

curl -sS https://api.doggiepay.com/v1/checkout/sessions \
  -H "Authorization: Bearer dp_live_sk_YOUR_SECRET" \
  -H "X-DoggiePay-Request-Id: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Idempotency-Key: order-1001-pay" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "19.99",
    "currency": "USDC",
    "chain": "BASE",
    "success_url": "https://merchant.example/orders/1001/paid",
    "cancel_url": "https://merchant.example/orders/1001/cancel",
    "metadata": { "order_id": "1001" }
  }'

响应里的 data 字段

建议在服务端用 Secret Key 创建会话，再只把 hosted_url（或 id + client_secret）交给前端。

创建失败时常见错误

2. 打开 Hosted 收银台

拿到 hosted_url 后，跳转或 window.open 即可。Hosted 页面在 https://pay.doggiepay.com。

可选：Button SDK

npm install @doggiepay/checkout

import { mountDoggiePayButton } from "@doggiepay/checkout";

mountDoggiePayButton("#pay", {
  hostedUrl,              // 来自服务端 create 响应
  openMode: "new_tab",    // 或 "same_tab"
  onPaid: () => refreshOrder(),
});

3. 查询会话状态

商户侧查询（Secret）

GET /v1/checkout/sessions/{id}

curl -sS "https://api.doggiepay.com/v1/checkout/sessions/SESSION_UUID" \
  -H "Authorization: Bearer dp_live_sk_YOUR_SECRET" \
  -H "X-DoggiePay-Request-Id: $(uuidgen | tr '[:upper:]' '[:lower:]')"

公开轮询（不带 Bearer，给 Hosted 用）

用 query 或 header 带上 client_secret：

GET /v1/checkout/sessions/{id}?client_secret=…
X-DoggiePay-Client-Secret: …

请不要只凭前端跳转就认定「已经付过款」。正式结论请看 Webhooks。

4. 取消会话

POST /v1/checkout/sessions/{id}/cancel
鉴权： Secret，或持有 client_secret（Hosted 上的取消）。

只有 cancellable === true 时能取消，一般是 pending 状态。

取消成功后会推送 checkout.cancelled。

5. 确认到账之后做什么

1. 以 checkout.paid webhook 作为是否到账的权威信号
2. 有需要时，再查一次 GET …/sessions/{id}，确认 status === "paid"
3. 用 payment_id 或 metadata.order_id 做幂等，把订单标为已支付，再发货或开通权益
4. 收到 checkout.expired / checkout.cancelled 时，记得释放库存

6. 退款（可选）

POST /v1/refunds — 需要 Secret。只适用于已支付的 Checkout Payment，不适用于 Customers 入金。

curl -sS https://api.doggiepay.com/v1/refunds \
  -H "Authorization: Bearer dp_live_sk_YOUR_SECRET" \
  -H "X-DoggiePay-Request-Id: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "SESSION_UUID",
    "amount": "19.99",
    "currency": "USDC",
    "chain": "BASE",
    "to_address": "0xBuyer…"
  }'

后续进度可看 refund.* webhook，或调用 GET /v1/refunds。

7. 接下来可以看什么

• Webhooks — 用 HMAC 校验 checkout.paid
• Customers 产品线 — App 内长期充值地址与代客提现