Atualizar Método de Pagamento - Dodo Payments Documentation

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);

{
  "client_secret": "<string>",
  "expires_on": "2023-11-07T05:31:56Z",
  "payment_id": "<string>",
  "payment_link": "<string>"
}

Atualize o método de pagamento para uma assinatura. Este endpoint suporta tanto assinaturas ativas quanto assinaturas no estado on_hold.

Para assinaturas no estado on_hold, atualizar o método de pagamento cria automaticamente uma cobrança pelos valores remanescentes, gera uma fatura e reativa a assinatura para o estado active após o pagamento ser bem-sucedido.

Casos de Uso

Assinaturas ativas: Atualize o método de pagamento quando um cartão expira ou o cliente deseja usar um método de pagamento diferente
Assinaturas em espera: Reative assinaturas que foram colocadas em espera devido a falhas de pagamento atualizando o método de pagamento
Gerenciamento de métodos de pagamento: Troque entre métodos de pagamento salvos ou adicione novos

Para listar os métodos de pagamento existentes de um cliente, use a List Payment Methods API. Isso ajuda a recuperar os IDs dos métodos de pagamento disponíveis ao usar type: "existing" para atualizar o método de pagamento de uma assinatura.

Comportamento para Assinaturas Ativas

Ao atualizar o método de pagamento para uma assinatura ativa:

O método de pagamento é atualizado imediatamente
Nenhuma cobrança é criada
A assinatura permanece ativa
As renovações futuras usarão o novo método de pagamento

Comportamento para Assinaturas em Espera

Ao atualizar o método de pagamento de uma assinatura no estado on_hold:

Uma cobrança é criada automaticamente pelos valores remanescentes
Uma fatura é gerada para a cobrança
O pagamento é processado usando o novo método de pagamento
Após o pagamento ser bem-sucedido, a assinatura é reativada para o estado active
Você receberá eventos de webhook: payment.succeeded seguido por subscription.active

Se o pagamento falhar após atualizar o método de pagamento de uma assinatura on_hold, a assinatura permanecerá no estado on_hold. Monitore os eventos de webhook para acompanhar o status do pagamento.

Eventos de Webhook

Ao atualizar um método de pagamento para uma assinatura on_hold, você receberá os seguintes eventos de webhook:

payment.succeeded - A cobrança pelos valores remanescentes foi bem-sucedida
subscription.active - A assinatura foi reativada

Autorizações

Authorization

string

header

obrigatório

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

Parâmetros de caminho

subscription_id

string

obrigatório

Subscription Id

Corpo

application/json

New
Existing

type

enum<string>

obrigatório

Opções disponíveis:

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.

Opções disponíveis:

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

Resposta

Payment method updated

client_secret

string | null

expires_on

string<date-time> | null

payment_id

string | null

payment_link

string | null

Última modificação em 1 de abril de 2026

Criar AssinaturaCrie uma assinatura para um cliente.

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);

{
  "client_secret": "<string>",
  "expires_on": "2023-11-07T05:31:56Z",
  "payment_id": "<string>",
  "payment_link": "<string>"
}

​Casos de Uso

​Comportamento para Assinaturas Ativas

​Comportamento para Assinaturas em Espera

​Eventos de Webhook

Autorizações

Parâmetros de caminho

Corpo

Resposta

Casos de Uso

Comportamento para Assinaturas Ativas

Comportamento para Assinaturas em Espera

Eventos de Webhook