Saltar al contenido principal

Cómo funciona por dentro

No necesitas saber esto para integrarte, pero ayuda a entender por qué la API se comporta como se comporta: por qué el retorno del navegador no confirma un pago, por qué un webhook puede llegar dos veces y por qué nunca se cobra dos veces.

Cómo viaja un pago: tu sistema, la API de pagos, el registro transaccional, el procesador de eventos y los proveedoresTUS SISTEMASSistema ASistema BApp XREST /v1API de pagosAPI key · rate limitIdempotency-Keycrear · consultarconectoresWebpay PlusTransbank · redirect POSTCheckout ProMercado Pago · Orders APIsimulador · sandboxaprobar · rechazarwebhook + consultauna transacciónRegistro transaccionalestadoconsultaseventosdedupProcesador de eventospublica cada eventoactualiza consultasavisos del proveedorwebhooks a tu sistemaBUS DE EVENTOSpagosconectores · webhooksconciliaciónentregas agotadaswebhook firmado HMAC-SHA256 al consumidor
pedido del consumidorevento guardado con el cambioaplicado una sola vezwebhook saliente

Un pago, de punta a punta​

  1. Tu sistema llama a la API con su API key. La API valida el request, aplica el límite de solicitudes y la idempotencia.
  2. La API habla con el proveedor a través de un conector por proveedor (Webpay Plus, Mercado Pago o el simulador). Tu sistema nunca ve las diferencias entre ellos.
  3. Cada cambio de estado se guarda junto con su evento, en la misma transacción. Si algo falla a mitad de camino, o se guardan los dos o ninguno: nunca hay un pago autorizado sin su evento.
  4. Un procesador publica los eventos y los entrega a quienes los necesitan: las consultas, la conciliación y los webhooks hacia tu sistema.
  5. Los avisos de los proveedores (retorno del navegador, webhooks de Mercado Pago) se verifican, se registran y se contrastan con el proveedor antes de cambiar un estado.

Por qué no se pierde ni se duplica nada​

Cada cambio de estado se guarda con su evento, se publica y se aplica una sola vezTu pedidocrear intentpedir checkout…Una transacciónnuevo estado+ su eventoPublicadortoma lo pendientey lo publicaBus de eventosen orden por pagodurableConsumidoresregistran eventIdy aplican efectoseventId repetidoack sin efectossi el bus no responde, los eventos esperanse reintenta con backoff; nada se pierdeAL MENOS UNA VEZ EN TRANSPORTEexactamente una vez en el efecto de negocio
evento publicado tras el commitentrega duplicada: se reconoce y no tiene efecto
  • Los eventos se entregan al menos una vez: si algo falla, se reintenta hasta que se entreguen.
  • Cada consumidor recuerda qué eventos ya aplicó, así un evento repetido no produce un segundo efecto.
  • Tu sistema debe hacer lo mismo con los webhooks: usa el id del evento como clave única. Ver Webhooks.

Qué garantías te da esto​

GarantíaCómo te afecta
Un pago se autoriza solo con la confirmación del proveedorusa el webhook o GET /v1/payment-intents/{id}, no el retorno del navegador
Cada evento de un pago se publica en orden y al menos una veztus webhooks pueden repetirse; aplícalos de forma idempotente
Las operaciones que mueven dinero son idempotentesreintenta con la misma Idempotency-Key sin miedo
Los pagos en curso se concilian con el proveedorun aviso perdido no deja un pago colgado (Conciliación)