Saltar al contenido 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', {
  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>"
}
Actualiza el método de pago para una suscripción. Este endpoint admite tanto suscripciones activas como suscripciones en estado on_hold.
Para suscripciones en estado on_hold, actualizar el método de pago crea automáticamente un cargo por los adeudos restantes, genera una factura y reactiva la suscripción al estado active tras un pago exitoso.

​
Casos de Uso

  • Suscripciones activas: Actualiza el método de pago cuando una tarjeta expira o el cliente quiere usar un método de pago diferente
  • Suscripciones en espera: Reactiva suscripciones que se pusieron en espera debido a pagos fallidos actualizando el método de pago
  • Gestión de métodos de pago: Cambia entre métodos de pago guardados o agrega nuevos
Para listar los métodos de pago existentes de un cliente, utiliza la List Payment Methods API. Esto te ayuda a obtener los IDs de métodos de pago disponibles cuando usas type: "existing" para actualizar el método de pago de una suscripción.

​
Comportamiento para Suscripciones Activas

Al actualizar el método de pago para una suscripción activa:
  • El método de pago se actualiza inmediatamente
  • No se crea ningún cargo
  • La suscripción permanece activa
  • Las renovaciones futuras utilizarán el nuevo método de pago

​
Comportamiento para Suscripciones en Espera

Al actualizar el método de pago de una suscripción en estado on_hold:
  1. Se crea automáticamente un cargo por los adeudos restantes
  2. Se genera una factura por el cargo
  3. El pago se procesa con el nuevo método de pago
  4. Tras un pago exitoso, la suscripción se reactiva al estado active
  5. Recibirás eventos webhook: payment.succeeded seguido de subscription.active
Si el pago falla después de actualizar el método de pago de una suscripción en estado on_hold, la suscripción permanecerá en ese estado. Supervisa los eventos webhook para seguir el estado del pago.

​
Eventos de Webhook

Al actualizar un método de pago para una suscripción en estado on_hold, recibirás los siguientes eventos webhook:
  1. payment.succeeded - El cargo por los adeudos restantes fue exitoso
  2. subscription.active - La suscripción ha sido reactivada

Autorizaciones

​
Authorization
string
header
requerido

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

Parámetros de ruta

​
subscription_id
string
requerido

Subscription Id

Cuerpo

application/json
​
type
enum<string>
requerido
Opciones disponibles:
new
​
return_url
string | null

Respuesta

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 1, 2026