Skip to main content
Un webhook es una llamada POST que TapiPay hace a un endpoint tuyo cuando pasa algo que te importa: un pago se confirma, un cobro se rechaza o un cargo se revierte. Así te enteras al momento, sin consultar la API en loop.
Los webhooks no los emite la API, que no los implementa. Los emiten las plataformas de cobro de TapiPay, y se configuran durante el onboarding: no hay endpoint para darlos de alta ni para cambiar la URL.

​
Los eventos

Enruta por el campo type. Todos los eventos llegan al mismo endpoint tuyo, así que type es lo que te dice cuál es cuál. No infieras el evento por los campos que trae el payload.Con una salvedad: en la notificación de pago, type describe qué se cobró, no qué pasó. Lo que te dice si ese pago se confirmó, falló o se revirtió es su campo status. En los otros cinco, en cambio, el type ya identifica el hecho.
La notificación de pago viene de la plataforma de pago referenciado y tiene su propio contrato, distinto del resto: su status va en minúsculas, su type no identifica el evento sino el tipo de operación, y su configuración se documenta en esa misma página. Los otros cinco comparten todo lo que sigue.

​
Fallo y contracargo no son lo mismo

Los cinco eventos de esta familia se dividen en dos grupos, y conviene no confundirlos: dicen cosas distintas sobre el mismo cobro.

Fallo

El cobro nunca se concretó. Llegan con status: "FAILED".

Contracargo

El cobro se había concretado y después se revirtió. No traen status, porque no describen el estado de un pago sino un hecho posterior sobre un cargo ya procesado.

​
Campos comunes

Los cinco eventos comparten esta base:
companyCode, companyName y hash siempre están presentes como clave, aunque valgan null. Puedes leerlos sin verificar existencia, pero sí tienes que contemplar el null antes de usar el valor.

​
El hash de verificación

Tu endpoint es público, así que cualquiera puede llamarlo. El campo hash te deja confirmar que la petición viene de TapiPay y que el payload no fue alterado. Se genera cifrando con RSA contra la llave pública que entregas en el onboarding. Si no configuras una publicKey, el campo llega igual pero con valor null.
No asumas que hash viene con valor. Valida que no sea null antes de usarlo. Si tu integración depende de él para autenticar, un null inesperado significa que la llave pública no quedó configurada: confírmalo con TapiPay antes de salir a producción.
El hash es un mecanismo entre varios. Los demás (API Key, Bearer token, whitelist de IPs, mTLS) se configuran igual para todos los webhooks y están detallados en Notificación de pago.

​
El detalle de error es opcional

Los eventos de tarjeta pueden incluir el código y el mensaje de error que devolvió el proveedor, dentro de un objeto additionalData. Que lleguen o no depende de un flag de tu configuración, sendErrorInfo, que se define en el onboarding.
additionalData se omite por completo cuando queda vacío. No llega como objeto vacío ni con campos en null: directamente no está la clave. Verifica su existencia antes de leer adentro.
Queda omitido en dos casos: cuando sendErrorInfo está apagado, y cuando está prendido pero el proveedor no informó ningún detalle.
Los eventos de débito bancario funcionan distinto: el detalle del rechazo (bankErrorCode, bankErrorDescription) viaja siempre, en la raíz del payload y sin depender de sendErrorInfo.

​
Idempotencia

TapiPay puede reintentar una notificación, así que tu endpoint tiene que tolerar recibir el mismo evento más de una vez. La llave es operationId.
Guarda los operationId ya procesados en almacenamiento persistente (una tabla con índice único, o Redis), nunca en memoria del proceso: si reinicias el servidor entre el intento original y el reintento, una marca en memoria se pierde y el evento se procesa dos veces.
Los requisitos de tu endpoint (responder 2xx, en menos de 5 segundos, ser alcanzable desde las IPs de TapiPay) son los mismos para todos los webhooks y están en Notificación de pago.
Cada intento de envío queda registrado del lado de TapiPay, con su resultado, así que una notificación que creas perdida se puede rastrear.