Pular para o conteúdo principal
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', { 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.

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:
  1. Uma cobrança é criada automaticamente pelos valores remanescentes
  2. Uma fatura é gerada para a cobrança
  3. O pagamento é processado usando o novo método de pagamento
  4. Após o pagamento ser bem-sucedido, a assinatura é reativada para o estado active
  5. 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:
  1. payment.succeeded - A cobrança pelos valores remanescentes foi bem-sucedida
  2. 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
​
type
enum<string>
obrigatório
Opções disponíveis:
new
​
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
Last modified on April 8, 2026