Recursos para IA

Recuperar pagos recurrentes

Cuando un pago recurrente es rechazado, la acción adecuada depende del motivo del rechazo: algunos son temporales y se resuelven reintentando el cobro, mientras que otros requieren que el cliente actualice su medio de pago. Esta guía explica cómo consultar un pago rechazado, identificar el motivo a través de su campo status_detail y definir una estrategia de reintentos y comunicación para cada caso.

Estrategia de reintentos

Ante un rechazo, Mercado Pago ya ejecuta reintentos automáticos de forma nativa: una retentativa síncrona inmediata con otro adquirente y, si el pago tiene binary_mode = false, una optimización vía adquirentes batch.

Si tras esos intentos internos el pago sigue rechazado, debes gestionar la estrategia de reintentos según el motivo de cada rechazo: determinas la cadencia de los próximos intentos (por ejemplo, 24hs., 48hs. o 7 días), decides cuándo conviene reintentar y cuándo solicitar al cliente que actualice su medio de pago, y te encargas de la comunicación en cada caso.

Los pasos a continuación describen cómo implementar esta estrategia de reintentos.

Configurar notificaciones Webhooks

Para que la estrategia de reintentos funcione, tu sistema necesita saber inmediatamente cuándo falla un pago y por qué motivo. Para eso, es necesario que configures tus notificaciones Webhooks y recibas alertas sobre la creación o actualización de un pago, lo que te permitirá tomar las acciones pertinentes.

Asegúrate de haber configurado tus notificaciones Webhooks para el tópico Pagos (payment). Si todavía no lo hiciste, sigue el paso a paso de la documentación de notificaciones Webhooks.

Ante eventos de creación o actualización de un pago, Mercado Pago enviará una notificación con el siguiente formato:

json
{
  "id": 12345,
  "live_mode": true,
  "type": "payment",
  "date_created": "2015-03-25T10:04:58.396-04:00",
  "user_id": 44444,
  "api_version": "v1",
  "action": "payment.created",
  "data": {
    "id": "132260878091"
  }
}

Esta notificación contiene solo el ID del pago, no su estado. Al recibirla, tu servidor debe consultar inmediatamente la API de Pagos para obtener los detalles completos.

Consultar el pago e identificar el código de rechazo

Para consultar el estado de un pago, envía una solicitud /v1/payments/{id}GET utilizando el ID recibido en la notificación.

curl -X GET \
  'https://api.mercadopago.com/v1/payments/{id}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

En la respuesta, localiza los dos campos que indican el código de rechazo y determinan tu próxima acción:

Campo	Descripción	Ejemplo
`status`	Estado actual del pago	`"rejected"`
`status_detail`	Motivo específico del rechazo	`"cc_rejected_insufficient_amount"`

Actuar según el código de rechazo

No todos los rechazos deben tratarse de la misma forma. La categorización correcta del error a partir de su status_detail determina si es necesario aplicar una lógica de reintento o si es necesario contactar al pagador.

Según su naturaleza, los rechazos se agrupan en tres categorías:

Soft Declines (errores temporales): el rechazo es temporal y hay alta probabilidad de aprobación en un reintento. Conviene reintentar siguiendo una cadencia.
Hard Declines (errores permanentes): el rechazo no se resuelve reintentando, e insistir puede afectar tu reputación con los adquirentes. No reintentes; el cliente debe actualizar su medio de pago.
Errores de llenado o configuración: requieren una corrección previa, ya sea del cliente o de tu integración. Reintenta solo después de corregir el dato o la configuración.

Mira cómo reconocer el tipo de error y qué acciones debes implementar a continuación.

`status_detail`	Qué significa	Acción	Comunicación recomendada
`cc_rejected_insufficient_amount`	Fondos insuficientes. El cliente no tiene saldo disponible.	Reintentar. Prioriza días de cobro, por ejemplo días 1–5 o 15–20 del mes. La cadencia sugerida es de 24hs., 48hs., 72hs.	Inmediata (automática): "Tu pago falló por fondos insuficientes. Asegúrate de tener saldo disponible. Reintentaremos en 24hs."
`cc_amount_rate_limit_exceeded`	Límite diario excedido. El cliente superó su límite diario de cobros.	Reintentar. Espera 24 horas y reintenta.	Inmediata (automática): "Tu pago falló por exceder el límite diario. Reintentaremos automáticamente en 24hs."
`cc_rejected_other_reason`	Rechazo genérico del banco. El emisor no dio un motivo específico.	Reintentar con precaución. Reintenta una vez en 24hs. Si vuelve a fallar, trátalo como hard decline.	Inmediata (automática): "Tu banco rechazó el pago sin darnos un motivo. Reintentaremos en 24hs. Si el problema persiste, contacta a tu banco."
`cc_rejected_call_for_authorize`	El banco solicita autorización del cliente para validar la compra.	No reintentar todavía. El reintento fallará hasta que el cliente autorice la compra en su banco.	Inmediata (acción requerida): "Tu banco bloqueó el pago y solicita tu autorización. Por favor, comunícate con tu banco para aprobar el cobro de [Nombre de la empresa]. Avísanos cuando lo hayas hecho para reintentar."
`cc_rejected_time_out` / `cc_rejected_expired_operation`	Timeout del procesador. Error técnico o de tiempo de espera.	Reintentar. Espera de 5 a 15 minutos y reintenta el cobro.	Ninguna comunicación es necesaria todavía. El cliente no tiene responsabilidad en el error. Reintenta 1 o 2 veces; si continúa fallando, notifica al cliente.

Definir estrategia de comunicación

En la mayoría de los flujos, Mercado Pago no contacta al cliente final en tu nombre. El gerenciamiento de la comunicación en casos de rechazo es responsabilidad del comercio y es tan importante como el reintento técnico.

Por esto, es necesario que definas una estrategia de comunicación teniendo en cuenta los siguientes puntos:

Define una ventana de recuperación: determina cuánto tiempo tiene el cliente para resolver el motivo de rechazo del pago antes de suspender el servicio.
Segmenta la comunicación por tipo de error:
- Soft Declines: usa un tono de baja fricción. Comunica que hubo un problema temporal y que el reintento se hará automáticamente.
- Hard Declines: usa un tono de urgencia. Informa que el servicio está en riesgo de suspensión y solicita la actualización inmediata del medio de pago.
Provee un enlace de actualización seguro: dirige al cliente a un portal seguro donde pueda actualizar su medio de pago, nunca solicites sus datos por otros medios. Cuando el cliente realice su actualización, ejecuta el cobro pendiente de inmediato.