Saltar al contenido principal
Cuando un usuario registra su cuenta bancaria en la página de enrolamiento, TapiPay te avisa con este webhook. Trae el externalPaymentMethodId de la cuenta, el mismo que devuelve GET /payment-methods y que acepta POST /v2/debts/orders, así que no necesitas consultar la API para empezar a cobrarle.
Este webhook tiene el mismo contrato que el pago de una orden: no trae operationId ni companyName, y su llave de idempotencia es id. Lo que se explica en Campos comunes no aplica acá, salvo el hash.

​
Cuándo llega

Llega cada vez que el registro de la cuenta termina bien:
  • Cuenta nueva: la primera vez que el usuario registra esa cuenta.
  • Registro repetido: el usuario vuelve a registrar una cuenta que ya tenía vigente.
  • Reactivación: el usuario vuelve a registrar una cuenta que se había eliminado.
En los dos últimos casos el aviso llega con el mismo id y el mismo registeredAt que el de la cuenta nueva. Es la misma cuenta, así que lo tratas como un reenvío. Por ahora el contrato cubre cuentas bancarias (BANK_ACCOUNT). Si te llega un aviso con otro type de medio, ignóralo: los demás tipos todavía no forman parte de este contrato. No llega si el registro falla, ni por las cuentas que TapiPay carga por fuera del registro, por ejemplo en una migración.

​
Configuración

Llega a la misma URL que los eventos de órdenes de pago: la que configuraste para órdenes en el onboarding o, si no tienes una propia, tu URL general. Los mecanismos de seguridad son los mismos que en el resto de los webhooks: ver Validar que la petición viene de TapiPay. POST con Content-Type: application/json. El header notificationType trae el mismo valor que type, para que puedas enrutar sin leer el cuerpo.

​
El payload

​
paymentMethod

Es el mismo objeto paymentMethod que llega en el pago de una orden, con dos campos más: isDefault y details.

​
El hash

Si entregaste una llave pública RSA en el onboarding, hash viene cifrado con ella. Descífralo con tu llave privada: contiene tu usuario de integración o, en la versión v2 de la seguridad, { "clientUsername", "operationId" }. En v2, comprueba que operationId coincida con el id del cuerpo.

​
Ejemplo

Corresponde a una integración sin llave pública, por eso hash viene en null.

​
Recomendaciones

  • Procesa cada id una sola vez. Además de los reintentos por falta de respuesta, el registro repetido y la reactivación reenvían el mismo id. Guarda los id procesados en almacenamiento persistente.
  • Guarda el externalPaymentMethodId junto a tu usuario: es lo que necesitas para cobrarle con esa cuenta.
  • No uses isDefault como fuente de verdad. La cuenta predeterminada puede cambiar después, por ejemplo si el usuario elimina una cuenta. Antes de decidir con qué cuenta cobrar, consulta GET /payment-methods.
  • Ignora los campos que no conozcas: se pueden agregar campos nuevos, también dentro de details.
Los requisitos de tu endpoint (responder 2xx en menos de 5 segundos y ser alcanzable desde las IPs de TapiPay) son los mismos que en el resto de los webhooks: ver Requisitos de tu endpoint.