跳转到主要内容
POST
/
subscriptions
/
{subscription_id}
/
update-payment-method
JavaScript
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});

const response = await client.subscriptions.updatePaymentMethod('subscription_id', { type: 'new' });

console.log(response.payment_id);
{
  "client_secret": "<string>",
  "expires_on": "2023-11-07T05:31:56Z",
  "payment_id": "<string>",
  "payment_link": "<string>"
}
更新订阅的付款方式。此端点同时支持处于活跃状态的订阅和处于on_hold状态的订阅。
对于处于on_hold状态的订阅，更新付款方式会自动为剩余欠款创建一笔费用、生成发票，并在付款成功后将订阅重新激活至active状态。

​
用例

  • 活跃订阅：当卡片过期或客户想使用不同的支付方式时更新支付方式
  • 暂停订阅：通过更新支付方式重新激活因付款失败而暂停的订阅
  • 支付方式管理：在保存的支付方式之间切换或添加新方式
要列出客户的现有付款方式，请使用列出付款方式 API。这有助于在使用type: "existing"更新订阅的付款方式时检索可用的付款方式 ID。

​
活跃订阅的行为

更新活跃订阅的支付方式时：
  • 支付方式立即更新
  • 不会创建收费
  • 订阅保持活跃
  • 未来的续订将使用新的支付方式

​
暂停订阅的行为

当为处于on_hold状态的订阅更新付款方式时：
  1. 自动为剩余欠款创建费用
  2. 为该费用生成发票
  3. 使用新的付款方式处理付款
  4. 付款成功后，订阅会重新激活至active状态
  5. 您会收到以下 Webhook 事件：payment.succeeded 随后是 subscription.active
如果在为处于on_hold状态的订阅更新付款方式后付款失败，订阅将保持在 on_hold 状态。请监控 Webhook 事件以跟踪付款状态。

​
Webhook 事件

在为处于on_hold状态的订阅更新付款方式时，您会收到以下 Webhook 事件：
  1. payment.succeeded - 剩余欠款的费用已成功
  2. subscription.active - 订阅已重新激活

授权

​
Authorization
string
header
必填

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

路径参数

​
subscription_id
string
必填

Subscription Id

请求体

application/json
​
type
enum<string>
必填
可用选项:
new
​
return_url
string | null

响应

Payment method updated

​
client_secret
string | null
​
expires_on
string<date-time> | null
​
payment_id
string | null
​
payment_link
string | null