Customers
为用户创建客户并获取充值地址
用 UUID 作为 ref_id 创建 Customer，拿到长期充值地址；用户链上充值后，凭 deposit.credited 在你自己的系统里给用户加余额。
为用户创建客户并获取充值地址
当你的 App 需要给终端用户长期可用的充值地址（之后还可能提现）时，走 Customers 这条产品线。它和 Checkout 不同：Checkout 是一次性收款会话。
开始前请先完成 快速开始（Secret Key + Request-Id），并接好 Webhooks。
用户在你的 App 注册
→ 你的服务端 POST /v1/customers
→ 把 wallets[].address 展示给用户
用户链上转入 USDC/USDT
→ Doggie Pay 记入你的商户资金池
→ 推送 webhook deposit.credited
→ 你按用户在本地加余额
1. 各自负责什么
| 事项 | Doggie Pay | 你的系统 |
|---|---|---|
| 用户是谁 | Customer，ref_id = 你侧用户 UUID | 账号、KYC、风控 |
| 充值地址 | 按链开立的长期地址（创建时下发） | 展示并绑定到对应用户 |
| 链上到账 | 贷记你的商户加密货币余额 | — |
| 用户可用余额 | 不维护 | 根据 deposit.credited 自己记账 |
| 密钥与回调 | Secret Key + 商户 Webhook | Secret 只放服务端；验签后再入账 |
这些对接接口不要用 Publishable Key，也不要用门户登录 JWT。
2. 创建客户
POST /v1/customers
鉴权： Secret + X-DoggiePay-Request-Id
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
ref_id | string（UUID） | 是 | 你侧用户 ID。创建后不可改，必须是 UUID |
name | string | 是 | 显示名 |
email | string | 是 | 邮箱 |
description | string | 否 | 备注 |
blockchains | string[] | 否 | 要开立的链；省略则开平台已启用的全部链 |
请求示例
curl -sS https://api.doggiepay.com/v1/customers \
-H "Authorization: Bearer dp_live_sk_YOUR_SECRET" \
-H "X-DoggiePay-Request-Id: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
-H "Content-Type: application/json" \
-d '{
"ref_id": "6ded84e7-5449-4a2b-9c1d-0afcce047b29",
"name": "张三",
"email": "[email protected]",
"description": "可选备注"
}'
响应 data 主要字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | uuid | Doggie Pay 侧的客户 id |
ref_id | uuid | 你传入的用户 id |
name / email / description | string | 资料字段 |
wallets | array | 充值地址列表（见下） |
created_at / updated_at | string | ISO-8601 |
wallets[] 每一项：
| 字段 | 类型 | 说明 |
|---|---|---|
blockchain | string | 链，例如 ETH |
currency | string | 例如 USDC、USDT |
address | string | 充值地址 |
status | string | 例如 active |
同一条链上，多个币种往往共用一个地址；接口按币种分行，方便你直接做 UI。
钱包会在同一次创建请求里开好。若开钱包失败，整笔创建失败，不会留下「有客户、没地址」的半成品。
请持久化 id、ref_id，以及你要展示给用户的地址。之后充值归属、提现，一律把这个 ref_id 字符串当作 external_user_id 使用。
创建失败时常见错误
| HTTP | error.code | 含义 |
|---|---|---|
| 400 | ref_id_required | 未传 ref_id |
| 400 | invalid_ref_id | 不是合法 UUID |
| 409 | customer_ref_id_conflict | 该商户下 ref_id 已存在 |
| 400 | no_enabled_chains | 当前没有可用链 |
| 429 | rate_limited | 创建过于频繁（可看 Retry-After） |
| 429 | customer_quota_exceeded | 超过商户客户数量上限 |
| 503 / 502 | circle_not_configured / circle_error | 钱包服务暂不可用 |
3. 查询与更新
均需 Secret + Request-Id。
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /v1/customers/{id} | 详情 + 当前已有钱包（不会自动补新链） |
GET | /v1/customers?ref_id={uuid} | 只存了 ref_id 时用来回查 |
GET | /v1/customers?page=1&per_page=20 | 分页列表；per_page 最大 100；列表项通常不含完整 wallets |
PATCH | /v1/customers/{id} | 可改 name / email / description；不能改 ref_id |
列表 data 大致形态：
{
"items": [{ "id": "…", "ref_id": "…", "name": "…", "email": "…" }],
"meta": { "page": 1, "per_page": 20, "total": 42 }
}
4. 之后补链或再查地址
平台新开了链，或你需要重新拉取地址时：
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /v1/wallets/ensure | body：{ "external_user_id": "<ref_id>", "blockchains": ["ETH"] }；blockchains 可省略 |
GET | /v1/wallets/{external_user_id} | 列出该用户已有长期地址（external_user_id = ref_id） |
5. 用户充值到账时
用户向 wallets[].address 转账
→ Doggie Pay 识别地址归属
→ 贷记你的商户资金池
→ POST 你的 webhook：type = deposit.credited
→ 你按 data.external_user_id（= ref_id）给本地用户加余额
| 建议 | 说明 |
|---|---|
| 以谁为准 | 用户「到账」请以 deposit.credited 为准，不要只看区块浏览器 |
| 幂等 | 同一事件可能重投；用事件 id 或业务键做幂等入账 |
| Circle | 你不会直接收到 Circle 的 webhook |
deposit.credited 的 data 通常含：deposit_id、amount、currency、external_user_id、blockchain、tx_hash、circle_tx_id 等。
验签与信封格式见 Webhooks。
6. 实践建议
ref_id用稳定的 UUID；若你侧 ID 不是 UUID，自己维护一张对照表。- 创建超时重试时，复用同一个 Request-Id 和同一份 JSON body。
- Secret Key 只放服务端。
- 下一篇：代用户提现。