Saltar al contenido principal

API 1.21.1 - Webhooks y correos del resultado de los pagos

· 3 min de lectura

Aquí resumimos lo que cambió para los integradores desde la entrada 1.21.0. Esta versión corrige el aviso del resultado de los pagos: los webhooks payment.approved y payment.failed empiezan a entregarse y el usuario que creó la orden recibe un correo con el resultado. Las rutas siguen bajo el prefijo /api/v1.

Sin cambios obligatorios

Ninguna operación cambia. Si ya consultas GET /orders/{uuid} para conocer el resultado de un pago, tu integración sigue funcionando igual. Para dejar de consultar una y otra vez, suscribe tu webhook a payment.approved y payment.failed.

Cambios de comportamiento​

Webhooks payment.approved y payment.failed​

Hasta la 1.21.0 se aceptaban en la suscripción, pero no generaban entregas. Desde la 1.21.1 se entregan:

EventoCuándo llegaCampo propio
payment.approvedLa orden pasa a PAID: compras de certificados (order_type = QUOTA_PURCHASE) y renovaciones (order_type = CERTIFICATE_RENEWAL)paid_at
payment.failedLa orden pasa a FAILED porque la entidad financiera rechazó el pagoreason: motivo en texto plano (máx. 200 caracteres) o, si la pasarela no lo informa, La entidad financiera no aprobó el pago.
  • Contenido de data: order_id (el UUID de la orden, el mismo de POST /orders y GET /orders/{uuid}), order_type, company_id, issuance_flow, quantity, vigencia, amount, currency, payment_provider, provider_reference, provider_transaction_id y payment_method_type, más paid_at o reason.
  • order_type distingue compras de renovaciones: una renovación llega con issuance_flow = BIOMETRIC, quantity = 1 y vigencia = 1, igual que la compra de un certificado biométrico, pero no agrega cupos. Si sumas cupos al recibir payment.approved, hazlo solo con QUOTA_PURCHASE.
  • Como máximo una vez por orden cada evento: los reenvíos de la pasarela, un rechazo tardío de una orden ya pagada o un segundo cobro aprobado no generan otra entrega. Una orden que recibió payment.failed todavía puede recibir payment.approved si después se aprueba otro intento de pago de esa misma orden: antes de crear una orden nueva, consulta GET /orders/{uuid}.
  • Sin evento: si la transacción queda en VOIDED o ERROR (la orden sigue en PENDING) o si una orden de renovación se anula porque el certificado dejó de ser renovable.
  • Respaldo: las entregas no se reintentan. Mantén la consulta de GET /orders/{uuid} para conciliar, sobre todo en las órdenes que lleven tiempo en PENDING.
  • La firma, las cabeceras, el tiempo de espera y la desactivación tras 10 fallos no cambian. certificate.expiring sigue sin generar entregas.

Ejemplo de entrega en Webhooks de pagos. Detalle en Webhooks.

Correos del resultado del pago​

El usuario que creó la orden recibe un correo cuando el pago se aprueba o se rechaza, con un enlace a sus certificados o a sus órdenes. En las renovaciones, los correos son propios de la renovación: el de pago aprobado indica dónde consultar la nueva fecha de vencimiento y el de pago rechazado, cómo iniciar de nuevo la renovación.

Documentación​

  • La referencia de Webhooks documenta la entrega de payment.approved y payment.failed y los campos order_type y reason.
  • Las guías explican los webhooks de pagos como alternativa a consultar GET /orders/{uuid}, que se mantiene como respaldo.

¿Vas a actualizar una integración existente? Revisa la guía paso a paso, los casos de uso y la solución de problemas.