Chuyển đến nội dung chính
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', {
  payment_method: { type: 'new' },
});

console.log(response.payment_id);
{
  "client_secret": "<string>",
  "expires_on": "2023-11-07T05:31:56Z",
  "payment_id": "<string>",
  "payment_link": "<string>"
}
Cập nhật phương thức thanh toán cho một đăng ký. Endpoint này hỗ trợ cả đăng ký đang hoạt động và đăng ký trong trạng thái on_hold.
Đối với các thuê bao ở trạng thái on_hold, việc cập nhật phương thức thanh toán sẽ tự động tạo một khoản phí cho số dư còn lại, tạo hóa đơn và tái kích hoạt thuê bao trở lại trạng thái active khi thanh toán thành công.

​
Trường hợp sử dụng

  • Đăng ký đang hoạt động: Cập nhật phương thức thanh toán khi thẻ hết hạn hoặc khách hàng muốn sử dụng một phương thức thanh toán khác
  • Đăng ký tạm hoãn: Kích hoạt lại các đăng ký đã tạm hoãn do thanh toán không thành công bằng cách cập nhật phương thức thanh toán
  • Quản lý phương thức thanh toán: Chuyển đổi giữa các phương thức thanh toán đã lưu hoặc thêm mới
Để liệt kê các phương thức thanh toán hiện có của khách hàng, hãy sử dụng List Payment Methods API. Điều này giúp bạn lấy các ID phương thức thanh toán có sẵn khi sử dụng type: "existing" để cập nhật phương thức thanh toán của thuê bao.

​
Hành vi đối với Đăng ký Đang Hoạt Động

Khi cập nhật phương thức thanh toán cho một đăng ký đang hoạt động:
  • Phương thức thanh toán được cập nhật ngay lập tức
  • Không có khoản phí nào được tạo ra
  • Đăng ký vẫn giữ trạng thái hoạt động
  • Các lần gia hạn trong tương lai sẽ sử dụng phương thức thanh toán mới

​
Hành vi đối với Đăng Ký Tạm Hoãn

Khi cập nhật phương thức thanh toán cho một thuê bao ở trạng thái on_hold:
  1. Một khoản phí được tự động tạo cho số dư còn lại
  2. Một hóa đơn được tạo cho khoản phí đó
  3. Thanh toán được xử lý bằng phương thức thanh toán mới
  4. Khi thanh toán thành công, thuê bao được tái kích hoạt về trạng thái active
  5. Bạn sẽ nhận được các sự kiện webhook: payment.succeeded tiếp theo là subscription.active
Nếu thanh toán thất bại sau khi cập nhật phương thức thanh toán cho một thuê bao ở trạng thái on_hold, thuê bao sẽ vẫn giữ nguyên trạng thái on_hold. Hãy theo dõi các sự kiện webhook để giám sát trạng thái thanh toán.

​
Sự kiện Webhook

Khi cập nhật phương thức thanh toán cho một thuê bao ở trạng thái on_hold, bạn sẽ nhận được các sự kiện webhook sau:
  1. payment.succeeded - Khoản phí cho số dư còn lại đã thành công
  2. subscription.active - Thuê bao đã được tái kích hoạt

Ủy quyền

​
Authorization
string
header
bắt buộc

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

Tham số đường dẫn

​
subscription_id
string
bắt buộc

Subscription Id

Nội dung

application/json
​
type
enum<string>
bắt buộc
Tùy chọn có sẵn:
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.

Tùy chọn có sẵn:
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

Phản hồi

Payment method updated

​
client_secret
string | null
​
expires_on
string<date-time> | null
​
payment_id
string | null
​
payment_link
string | null
Lần sửa đổi cuối 8 tháng 4, 2026