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>"
}
Atualize o método de pagamento para uma assinatura. Este endpoint suporta tanto assinaturas ativas quanto assinaturas em on_hold estado.
Para assinaturas em on_hold estado, atualizar o método de pagamento cria automaticamente uma cobrança para as pendências restantes, gera uma fatura e reativa a assinatura para o estado active após o pagamento 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 para um cliente, use a API List Payment Methods. Isso ajuda você 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 para uma assinatura em on_hold estado:
  1. Uma cobrança é criada automaticamente para as pendências restantes
  2. Uma fatura é gerada para a cobrança
  3. O pagamento é processado usando o novo método de pagamento
  4. Após o pagamento bem-sucedido, a assinatura é reativada para o estado active
  5. Você receberá eventos de webhook: payment.succeeded seguidos por subscription.active
Se o pagamento falhar após atualizar o método de pagamento para uma assinatura em 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 em on_hold, você receberá os seguintes eventos de webhook:
  1. payment.succeeded - A cobrança para as pendências restantes foi bem-sucedida
  2. subscription.active - A assinatura foi reativada

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
subscription_id
string
required

Subscription Id

Body

application/json
​
type
enum<string>
required
Opções disponíveis:
new
​
return_url
string | null

Response

Payment method updated

​
client_secret
string | null
​
expires_on
string<date-time> | null
​
payment_id
string | null
​
payment_link
string | null