● 支付方式与金库 · /v1

支付方式与金库

卡数据只存在于金库,你的系统里只有 token。支持复用、设为默认、删除。

列出客户的支付方式

GET /v1/vault/methods

Query 参数

customer_uid必填 string

响应 200

token string 金库引用。你的系统只应存这个值。
type string
is_default boolean
card_brand string
card_last4 string
card_exp_month integer
card_exp_year integer
network_token boolean 是否已升级为网络令牌(换卡不掉单)
customer_uid string
created_at string<date-time>
请求
curl -X GET https://api.baton.example/v1/vault/methods \
  -H "Authorization: Bearer sk_live_xxx"
响应 · 200
[
  {
    "token": "pm_7c2a91f4",
    "type": "card",
    "is_default": true,
    "card_brand": "visa",
    "card_last4": "4242",
    "card_exp_month": 12,
    "card_exp_year": 2029,
    "network_token": true,
    "customer_uid": "CUS20261116000041",
    "created_at": "2026-10-02T03:11:00Z"
  }
]

直传卡数据换 token

POST /v1/vault/methods

只有 H2H 模式需要这个接口,并且要求你持有 PCI DSS 认证。卡号必须放在数字信封里, 明文提交直接 400。签名要求是 L2(Ed25519)。

返回的 token 默认一次性;要复用请再调 vault 绑到客户上。 如果你没有 PCI 认证,用客户端会话 + SDK,卡号根本不会到你的服务器。

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

请求体

type必填 card
encrypted必填 object 数字信封。平台公钥加密随机 AES-256-GCM 密钥,该密钥加密卡号与 CVV。也可直接用 JWE(RSA-OAEP + A256GCM)
└key_id必填 string 平台公钥版本,轮换期旧密钥仍可解 6 个月
└enc_key必填 string
└nonce必填 string
└ciphertext必填 string
└tag必填 string
customer_uid string 传了就直接绑定到客户,省一次 vault 调用

响应 201

token string 金库引用。你的系统只应存这个值。
type string
is_default boolean
card_brand string
card_last4 string
card_exp_month integer
card_exp_year integer
network_token boolean 是否已升级为网络令牌(换卡不掉单)
customer_uid string
created_at string<date-time>

错误

400参数不合法
401密钥缺失、无效、与环境不匹配,或签名校验失败
请求
curl -X POST https://api.baton.example/v1/vault/methods \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "type": "card",
  "encrypted": {
    "key_id": "pk_2026q4",
    "enc_key": "base64...",
    "nonce": "base64...",
    "ciphertext": "base64...",
    "tag": "base64..."
  }
}'
响应 · 201
{
  "token": "pm_7c2a91f4",
  "type": "card",
  "is_default": false,
  "card_brand": "visa",
  "card_last4": "4242",
  "card_exp_month": 12,
  "card_exp_year": 2029,
  "network_token": false,
  "created_at": "2026-11-16T09:41:00Z"
}

存入金库

POST /v1/vault/methods/{token}/store

把一次性支付方式转成可复用 token,绑定到客户上。卡号不落你的库,也不落我们的业务库。

路径参数

token必填 string

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

请求体

customer_uid必填 string

响应 200

token string 金库引用。你的系统只应存这个值。
type string
is_default boolean
card_brand string
card_last4 string
card_exp_month integer
card_exp_year integer
network_token boolean 是否已升级为网络令牌(换卡不掉单)
customer_uid string
created_at string<date-time>
请求
curl -X POST https://api.baton.example/v1/vault/methods/{token}/store \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer_uid": "CUS20261116000041"
}'

设为默认

POST /v1/vault/methods/{token}/default

路径参数

token必填 string

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

响应 200

token string 金库引用。你的系统只应存这个值。
type string
is_default boolean
card_brand string
card_last4 string
card_exp_month integer
card_exp_year integer
network_token boolean 是否已升级为网络令牌(换卡不掉单)
customer_uid string
created_at string<date-time>
请求
curl -X POST https://api.baton.example/v1/vault/methods/{token}/default \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

删除支付方式

POST /v1/vault/methods/{token}/delete

立即失效,但已发起的订阅扣款不受影响。删除动作进审计日志。

路径参数

token必填 string

响应 200

uid string
deleted boolean
请求
curl -X POST https://api.baton.example/v1/vault/methods/{token}/delete \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."