메인 콘텐츠로 건너뛰기
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>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

구독의 결제 방법을 업데이트합니다. 이 엔드포인트는 활성 구독과 on_hold 상태의 구독 모두를 지원합니다.
on_hold 상태의 구독에 대해서 결제 수단을 업데이트하면 남은 금액에 대한 청구가 자동으로 발생하고, 청구서가 생성되며, 결제에 성공하면 구독이 active 상태로 다시 활성화됩니다.

​
사용 사례

  • 활성 구독: 카드가 만료되거나 고객이 다른 결제 방법을 사용하고 싶을 때 결제 방법 업데이트
  • 보류 중인 구독: 결제 실패로 인해 보류 중인 구독을 결제 방법을 업데이트하여 재활성화
  • 결제 방법 관리: 저장된 결제 방법 간 전환 또는 새 결제 방법 추가
고객의 기존 결제 수단을 나열하려면 List Payment Methods API를 사용하세요. 이를 통해 구독의 결제 수단을 업데이트할 때 type: "existing"를 사용할 수 있는 결제 수단 ID를 조회할 수 있습니다.

​
활성 구독에 대한 동작

활성 구독의 결제 방법을 업데이트할 때:
  • 결제 방법이 즉시 업데이트됩니다
  • 청구가 생성되지 않습니다
  • 구독은 활성 상태로 유지됩니다
  • 향후 갱신은 새 결제 방법을 사용합니다

​
보류 중인 구독에 대한 동작

on_hold 상태의 구독에 대해 결제 수단을 업데이트할 때:
  1. 남은 금액에 대한 청구가 자동으로 생성됩니다
  2. 청구에 대한 청구서가 발행됩니다
  3. 새로운 결제 수단으로 결제가 처리됩니다
  4. 결제에 성공하면 구독이 active 상태로 다시 활성화됩니다
  5. 다음 웹훅 이벤트를 수신합니다: payment.succeeded 다음에 subscription.active
on_hold 구독의 결제 수단을 업데이트한 후 결제가 실패하면 구독은 on_hold 상태로 유지됩니다. 웹훅 이벤트를 모니터링하여 결제 상태를 추적하세요.

​
웹훅 이벤트

on_hold 구독의 결제 수단을 업데이트할 때 다음 웹훅 이벤트를 수신합니다:
  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
Last modified on April 8, 2026