POST/api/v1/me/payment-methods绑定一个支付方式

Try it 面板需要启用 JavaScript。

以支付渠道 SDK 生成的临时 token 绑定支付方式；原文凭据经渠道直达 payment_service，Passport 其他服务不可见。

Request

Headers

Name	Data Type	Required	Description
Authorization	string	Yes	会话令牌认证，格式 `Bearer <sessionToken>`
Content-Type	string	Yes	请求体内容类型（默认值 "application/json"）

type RequestHeaders = {
  /** 会话令牌认证，格式 `Bearer <sessionToken>` */
  Authorization: string
  /** 请求体内容类型，默认值 "application/json" */
  Content-Type: string
}

{
  "Authorization": "Bearer st_7c1f9e05b28d4a63",
  "Content-Type": "application/json"
}

Body

Name	Data Type	Required	Description
providerToken	string	Yes	支付渠道临时 token（客户端 SDK 生成，一次性）
setAsDefault	boolean	No	是否设为默认支付方式

type RequestBody = {
  /** 支付渠道临时 token（客户端 SDK 生成，一次性） */
  providerToken: string
  /** 是否设为默认支付方式 */
  setAsDefault?: boolean
}

{
  "providerToken": "pm_tok_1N0sXe2mYq7Ld4Rw",
  "setAsDefault": true
}

Response

Body

PaymentMethodDTO

Name	Data Type	Required	Description
methodId	string	Yes	支付方式 ID
brand	string	Yes	品牌（visa / mastercard / alipay 等）
maskedNumber	string	Yes	脱敏尾号，如 **** 4242
expiry	string	No	有效期（MM/YY，卡片类才有）
isDefault	boolean	Yes	是否默认支付方式
addedAt	string	Yes	绑定时间

type PaymentMethodDTO = {
  /** 支付方式 ID */
  methodId: string
  /** 品牌（visa / mastercard / alipay 等） */
  brand: string
  /** 脱敏尾号，如 **** 4242 */
  maskedNumber: string
  /** 有效期（MM/YY，卡片类才有） */
  expiry?: string
  /** 是否默认支付方式 */
  isDefault: boolean
  /** 绑定时间 */
  addedAt: string
}

{
  "methodId": "01JD8SNR8N0S3W9ZS4W7ZFM1X5G",
  "brand": "visa",
  "maskedNumber": "**** 4242",
  "expiry": "09/28",
  "isDefault": true,
  "addedAt": "2026-10-14T11:40:00Z"
}

HTTP Code

HTTP Status	Meaning	Notes
200	成功	返回新支付方式
400	渠道 token 无效	providerToken 已使用、过期或不被渠道接受

Response Code

响应使用统一信封 {id, code, messages, result}，其 code 字段：

code	Meaning	Notes
0	成功	返回新支付方式
2801	渠道 token 无效	providerToken 校验失败
2802	支付方式被拒绝	渠道侧拒绝绑定该支付方式

Examples

POST /api/v1/me/payment-methods
Authorization: Bearer st_7c1f9e05b28d4a63
Content-Type: application/json

{
  "providerToken": "pm_tok_1N0sXe2mYq7Ld4Rw",
  "setAsDefault": true
}

{
  "id": "01JD8SOLSF0F2N9",
  "code": 0,
  "messages": [],
  "result": {
    "methodId": "01JD8SNR9N1T4W0AT5X8AGN2Y5H",
    "brand": "visa",
    "maskedNumber": "**** 4242",
    "expiry": "09/28",
    "isDefault": true,
    "addedAt": "2026-10-14T11:50:00Z"
  }
}

Remarks

首条支付方式自动成为默认；providerToken 一次性，绑定成功即失效。