快速开始

本文面向需要在自己的服务端对接 Doggie Pay 的开发者。读完后，你可以：

1. 分清 Checkout 与 Customers 两条产品线，选对接入方式
2. 正确使用密钥与请求头
3. 成功发出一次只读调用，确认环境可用

接口根地址

https://api.doggiepay.com

对接用接口都在 /v1/* 下。注意不要打到 /v1/portal/*（商户门户专用），也不要使用内部运维接口。

1. 先选产品线

• 走 Checkout → 下一篇：用 Checkout 收款
• 走 Customers → 另有专文（创建客户、入金、提现）
• 两条线共用鉴权、Request-Id，以及 Webhooks

有一点很重要：链上资金进入的是你的商户余额。如果产品里还有「用户余额」，需要由你自己的系统记账。

2. 接入前准备

1. 到 merchant.doggiepay.com 注册商户
2. 在门户创建 Secret Key（形如 dp_live_sk_…），只放在服务端（环境变量或 KMS）
3. 如需浏览器调用白名单接口，再创建 Publishable Key（dp_live_pk_…）
4. 配置 Webhook URL，并立刻保存页面上只展示一次的 webhook_secret（whsec_…）。详见 Webhooks

Secret Key 不要写进 App、前端页面或公开仓库。

3. 怎么鉴权

三种凭证

Publishable Key 能调哪些接口

除此之外的对接接口，一律需要 Secret Key。

对接请求必带的头

Authorization: Bearer dp_live_sk_YOUR_SECRET
X-DoggiePay-Request-Id: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

关于重试： 创建、更新类请求如果超时需要重试，请使用同一个 Request-Id（或 Idempotency-Key），并且 body 保持不变。同一 ID、不同 body，会返回 409 request_id_conflict。

4. 统一响应格式

成功时大致是：

{
  "data": { },
  "error": null
}

失败时大致是：

{
  "data": null,
  "error": {
    "code": "unauthorized",
    "message": "Bearer token required"
  }
}

5. 发出第一次请求

先查当前已启用的链（Secret、Publishable 都可以）：

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

返回的 data 可能类似：

{
  "chains": ["ETH", "BASE"]
}

也可以查代币列表（可加 ?currency=USDC）：

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

6. 常见错误码

7. 接下来可以看什么

1. 用 Checkout 收款 — 创建收款会话，打开 Hosted 收银台
2. Webhooks — 验签；收到 checkout.paid 后再把订单标为已支付
3. 前端需要支付按钮时，安装 @doggiepay/checkout

常用域名