更新支付方式

更新现有订阅的支付方式。您可以添加新的支付方式或使用客户保存的支付方式中的现有方式。

POST /subscriptions/{subscription_id}/update-payment-method

JavaScript

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', {
  payment_method: { type: 'new' },
});

console.log(response.payment_id);

200

{
  "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

New

Existing

type · enum<string> · 必填

可用选项: new

allowed_payment_method_types · enum<string>[] | null

List of payment methods allowed during checkout.

Customers will never see payment methods that are not in this list. However, adding a method here does not guarantee customers will see it. Availability still depends on other factors (e.g., customer location, merchant settings).

All supported payment method types (from Hyperswitch).

Used for disabled-payment-methods filtering and validation.

可用选项: ach, affirm, afterpay_clearpay, alfamart, ali_pay, ali_pay_hk, alma, amazon_pay, apple_pay, atome, bacs, bancontact_card, becs, benefit, bizum, blik, boleto, bca_bank_transfer, bni_va, bri_va, card_redirect, cimb_va, classic, credit, crypto_currency, cashapp, dana, danamon_va, debit, duit_now, efecty, eft, eps, fps, evoucher, giropay, givex, google_pay, go_pay, gcash, ideal, interac, indomaret, klarna, kakao_pay, local_bank_redirect, mandiri_va, knet, mb_way, mobile_pay, momo, momo_atm, multibanco, online_banking_thailand, online_banking_czech_republic, online_banking_finland, online_banking_fpx, online_banking_poland, online_banking_slovakia, oxxo, pago_efectivo, permata_bank_transfer, open_banking_uk, pay_bright, paypal, paze, pix, pay_safe_card, przelewy24, prompt_pay, pse, red_compra, red_pagos, samsung_pay, sepa, sepa_bank_transfer, sofort, sunbit, swish, touch_n_go, trustly, twint, upi_collect, upi_intent, vipps, viet_qr, venmo, walley, we_chat_pay, seven_eleven, lawson, mini_stop, family_mart, seicomart, pay_easy, local_bank_transfer, mifinity, open_banking_pis, direct_carrier_billing, instant_bank_transfer, billie, zip, revolut_pay, naver_pay, payco

return_url · string | null

响应

200

application/json

Payment method updated

client_secret · string | null

expires_on · string<date-time> | null

payment_id · string | null

payment_link · string | null