> ## 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](/api-reference/customers/get-customer-payment-methods)를 사용하세요. 이를 통해 구독의 결제 수단을 업데이트할 때 `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`** - 구독이 다시 활성화되었습니다
## OpenAPI
````yaml post /subscriptions/{subscription_id}/update-payment-method
openapi: 3.1.0
info:
title: public
description: ''
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 1.106.2
servers:
- url: https://test.dodopayments.com/
description: Test Mode Server Host
- url: https://live.dodopayments.com/
description: Live Mode Server Host
security: []
tags:
- name: Products
- name: Payments
- name: Subscriptions
- name: Addons
- name: Customers
- name: Refunds
- name: Disputes
- name: Events
- name: License Keys
- name: Entitlements
- name: Licenses
- name: Discounts
- name: Meters
- name: Credit Entitlements
- name: Credit Entitlement Balances
- name: Outgoing Webhooks
- name: Checkout
- name: Webhook Events
- name: Payment Connector Webhooks
paths:
/subscriptions/{subscription_id}/update-payment-method:
post:
tags:
- Subscriptions
operationId: update
parameters:
- name: subscription_id
in: path
description: Subscription Id
required: true
schema:
type: string
example: sub_Iuaq622bbmmfOGrVTqdXv
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePaymentMethodReq'
required: true
responses:
'200':
description: Payment method updated
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePaymentMethodResponse'
'422':
description: Invalid Request Object or Parameters
'500':
description: Something went wrong :(
security:
- API_KEY: []
x-codeSamples:
- lang: JavaScript
source: >-
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);
- lang: Python
source: |-
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)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/dodopayments/dodopayments-go\"\n\t\"github.com/dodopayments/dodopayments-go/option\"\n)\n\nfunc main() {\n\tclient := dodopayments.NewClient(\n\t\toption.WithBearerToken(\"My Bearer Token\"),\n\t)\n\tresponse, err := client.Subscriptions.UpdatePaymentMethod(\n\t\tcontext.TODO(),\n\t\t\"sub_Iuaq622bbmmfOGrVTqdXv\",\n\t\tdodopayments.SubscriptionUpdatePaymentMethodParams{\n\t\t\tPaymentMethod: dodopayments.SubscriptionUpdatePaymentMethodParamsPaymentMethodNew{\n\t\t\t\tType: dodopayments.F(dodopayments.SubscriptionUpdatePaymentMethodParamsPaymentMethodNewTypeNew),\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.PaymentID)\n}\n"
- lang: Java
source: >-
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);
}
}
- lang: Kotlin
source: >-
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)
}
- lang: Ruby
source: |-
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)
- lang: PHP
source: |-
subscriptions->updatePaymentMethod(
'sub_Iuaq622bbmmfOGrVTqdXv',
paymentMethod: [
'type' => 'new',
'allowedPaymentMethodTypes' => [PaymentMethodTypes::ACH],
'returnURL' => 'return_url',
],
);
var_dump($response);
} catch (APIException $e) {
echo $e->getMessage();
}
- lang: C#
source: >-
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);
- lang: Rust
source: |-
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(())
}
components:
schemas:
UpdatePaymentMethodReq:
oneOf:
- type: object
title: New
required:
- type
properties:
allowed_payment_method_types:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/PaymentMethodTypes'
description: >-
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).
uniqueItems: true
return_url:
type:
- string
- 'null'
type:
type: string
enum:
- new
x-stainless-const: true
- type: object
title: Existing
required:
- payment_method_id
- type
properties:
payment_method_id:
type: string
type:
type: string
enum:
- existing
x-stainless-const: true
discriminator:
propertyName: type
UpdatePaymentMethodResponse:
type: object
properties:
client_secret:
type:
- string
- 'null'
expires_on:
type:
- string
- 'null'
format: date-time
payment_id:
type:
- string
- 'null'
payment_link:
type:
- string
- 'null'
PaymentMethodTypes:
type: string
description: |-
All supported payment method types.
Used for disabled-payment-methods filtering and validation.
enum:
- 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
securitySchemes:
API_KEY:
type: http
scheme: bearer
````