Estados del pago

Consulta el pago desde tu servidor y usa su campo status para decidir qué hacer:

Estado	Qué hacer
requires_customer_action	Lleva al cliente a checkout.url para que continúe el pago. Si tiene lastDecline, el último intento fue rechazado y el cliente puede intentarlo de nuevo.
processing	El pago está en curso. Espera y consulta el mismo pago.
verifying	El resultado todavía no se conoce. Espera; no inicies otro pago.
partially_paid	Se cobró una parte de un pago dividido, pero falta dinero por cobrar.
succeeded	El pago está confirmado. Marca el pedido como pagado una sola vez.
canceled	El pago terminó cancelado.
expired	El Checkout no se completó antes de expiresAt. Crea otro pago si el cliente aún quiere pagar; para una suscripción, consulta la regla de abajo.

Los estados succeeded, canceled y expired indican que el pago terminó. Si vuelves a enviar su paymentReference, recibirás ese mismo pago, sin iniciar otro pago. Para cobrar de nuevo necesitas otra referencia, pero primero confirma qué pasó con el anterior y resuelve cualquier parte pendiente.

Intentos rechazados

Un rechazo termina el intento, no el pago. El pago vuelve a requires_customer_action y lastDecline indica el motivo normalizado (code), un mensaje para el cliente (message) y cuándo ocurrió (attemptedAt). El cliente puede volver a intentarlo con el mismo link hasta que el pago venza. Cada intento rechazado envía el webhook payment.declined. No crees otro pago por un rechazo.

Plazo del pago

expiresAt indica cuándo vence el Checkout. Por defecto son 30 minutos con returnUrl y 1 hora sin él; envía expiresAfterSeconds al crear el pago para cambiarlo, entre 300 y 86400 segundos. Define cuánto tiempo queda abierto el QR.

Pagos de suscripción

El primer pago para configurar una suscripción vence a las 24 horas. Si vence, la suscripción termina; para empezar de nuevo, crea otra con una subscriptionReference nueva. Una renovación puede seguir en requires_customer_action con expiresAt y checkout.expiresAt en null hasta que el proveedor de email acepte el envío del aviso de pago pendiente. Entonces Timbro fija el vencimiento en 7 días. Mantén disponible el link de Checkout y no muestres una cuenta regresiva mientras la fecha sea null. Reenviar el aviso no extiende un vencimiento ya fijado. Si el proveedor rechaza el aviso, recoveryNotice.problem es notice_handoff_failed y Timbro no lo reintenta: comparte el link o reenvía el aviso. Cada pago admite 3 reenvíos en 24 horas.

División de pagos

Al dividir una cuenta, Timbro puede retener el monto de cada parte en su tarjeta antes de cobrarlo. Un monto retenido todavía no confirma el pago.

• partially_authorized o authorized: hay montos retenidos en las tarjetas.
• capturing: Timbro está cobrando los montos retenidos.
• releasing: Timbro está liberando los montos retenidos.
• partially_paid: se cobró una parte, pero pueden quedar otras pendientes.

Revisa el detalle de cada parte en split antes de dar la cuenta por pagada.

Si pediste un e-CF

succeeded confirma el pago, no la aceptación fiscal. Consulta el e-CF por su invoiceId para revisar el estado y los archivos. Facturar al momento del pago.

Confirmar un pago sin respuesta