메인 콘텐츠로 건너뛰기
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('sub_Iuaq622bbmmfOGrVTqdXv', {
  payment_method: { type: 'new' },
});

console.log(response.payment_id);
import os
from dodopayments import DodoPayments

client = DodoPayments(
bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"), # This is the default and can be omitted
)
response = client.subscriptions.update_payment_method(
subscription_id="sub_Iuaq622bbmmfOGrVTqdXv",
payment_method={
"type": "new"
},
)
print(response.payment_id)
package main

import (
"context"
"fmt"

"github.com/dodopayments/dodopayments-go"
"github.com/dodopayments/dodopayments-go/option"
)

func main() {
client := dodopayments.NewClient(
option.WithBearerToken("My Bearer Token"),
)
response, err := client.Subscriptions.UpdatePaymentMethod(
context.TODO(),
"sub_Iuaq622bbmmfOGrVTqdXv",
dodopayments.SubscriptionUpdatePaymentMethodParams{
PaymentMethod: dodopayments.SubscriptionUpdatePaymentMethodParamsPaymentMethodNew{
Type: dodopayments.F(dodopayments.SubscriptionUpdatePaymentMethodParamsPaymentMethodNewTypeNew),
},
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.PaymentID)
}
package com.dodopayments.api.example;

import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
import com.dodopayments.api.models.subscriptions.SubscriptionUpdatePaymentMethodParams;
import com.dodopayments.api.models.subscriptions.SubscriptionUpdatePaymentMethodResponse;

public final class Main {
private Main() {}

public static void main(String[] args) {
DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();

SubscriptionUpdatePaymentMethodParams params = SubscriptionUpdatePaymentMethodParams.builder()
.subscriptionId("sub_Iuaq622bbmmfOGrVTqdXv")
.paymentMethod(SubscriptionUpdatePaymentMethodParams.PaymentMethod.New.builder().build())
.build();
SubscriptionUpdatePaymentMethodResponse response = client.subscriptions().updatePaymentMethod(params);
}
}
package com.dodopayments.api.example

import com.dodopayments.api.client.DodoPaymentsClient
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient
import com.dodopayments.api.models.subscriptions.SubscriptionUpdatePaymentMethodParams
import com.dodopayments.api.models.subscriptions.SubscriptionUpdatePaymentMethodResponse

fun main() {
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

val params: SubscriptionUpdatePaymentMethodParams = SubscriptionUpdatePaymentMethodParams.builder()
.subscriptionId("sub_Iuaq622bbmmfOGrVTqdXv")
.paymentMethod(SubscriptionUpdatePaymentMethodParams.PaymentMethod.New.builder().build())
.build()
val response: SubscriptionUpdatePaymentMethodResponse = client.subscriptions().updatePaymentMethod(params)
}
require "dodopayments"

dodo_payments = Dodopayments::Client.new(
bearer_token: "My Bearer Token",
environment: "test_mode" # defaults to "live_mode"
)

response = dodo_payments.subscriptions.update_payment_method(
"sub_Iuaq622bbmmfOGrVTqdXv",
payment_method: {type: :new}
)

puts(response)
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Dodopayments\Client;
use Dodopayments\Core\Exceptions\APIException;
use Dodopayments\Payments\PaymentMethodTypes;

$client = new Client(
bearerToken: getenv('DODO_PAYMENTS_API_KEY') ?: 'My Bearer Token',
environment: 'test_mode',
);

try {
$response = $client->subscriptions->updatePaymentMethod(
'sub_Iuaq622bbmmfOGrVTqdXv',
paymentMethod: [
'type' => 'new',
'allowedPaymentMethodTypes' => [PaymentMethodTypes::ACH],
'returnURL' => 'return_url',
],
);

var_dump($response);
} catch (APIException $e) {
echo $e->getMessage();
}
using System;
using DodoPayments.Client;
using DodoPayments.Client.Models.Payments;
using DodoPayments.Client.Models.Subscriptions;

DodoPaymentsClient client = new();

SubscriptionUpdatePaymentMethodParams parameters = new()
{
SubscriptionID = "sub_Iuaq622bbmmfOGrVTqdXv",
PaymentMethod = new New()
{
AllowedPaymentMethodTypes =
[
PaymentMethodTypes.Ach
],
ReturnUrl = "return_url",
},
};

var response = await client.Subscriptions.UpdatePaymentMethod(parameters);

Console.WriteLine(response);
use dodopayments::Client;

#[tokio::main]
async fn main() -> dodopayments::Result<()> {
let client = Client::from_env()?;
let subscription_id = "subscription_id";
let result = client
.subscriptions()
.update_payment_method()
.subscription_id(subscription_id)
.body(serde_json::json!({"type":"new","allowed_payment_method_types":["ach"],"return_url":"return_url"}))
.await?;
println!("{result:?}");
Ok(())
}
curl --request POST \
--url https://test.dodopayments.com/subscriptions/{subscription_id}/update-payment-method \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "new",
"allowed_payment_method_types": [],
"return_url": "<string>"
}
'
{
  "client_secret": "<string>",
  "expires_on": "2023-11-07T05:31:56Z",
  "payment_id": "<string>",
  "payment_link": "<string>"
}
구독의 결제 방법을 업데이트합니다. 이 엔드포인트는 활성 구독과 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
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.

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,
satispay
return_url
string | null

응답

Payment method updated

client_secret
string | null
expires_on
string<date-time> | null
payment_id
string | null
마지막 수정일 2026년 4월 1일