Payin Notifications
Una visión general del producto Payin Notifications
Payins Notifications
Una 💰🔔Payin Notification ("notificación de payin") es un mensaje enviado por Shinkansen hacia un participante de la red (cliente de Shinkansen) que notifica una entrada de dinero a una cuenta bancaria.
Un mini-glosario antes de continuar:
- Participant(e): Una fintech/startup que está conectada a la red Shinkansen y desea recibir notificaciones sobre las entradas de dinero en su cuenta.
- Debtor: En el contexto de Payins, es el originador del movimiento, es decir, quien envió el dinero.
- Creditor: En el contexto de Payins, es el destinatario del movimiento, es decir, el Participante.
- Creditor FI (financial institution): entidad financiera donde el Participante tiene una cuenta corriente y de la cual Shinkansen recibe o extrae la información.
Desde el punto de vista de quien recibe una 💰🔔Payin Notification es básicamente un webhook:
Contenido de las Payin Notifications
Si bien el contenido de la notificación puede variar (muy ligeramente) entre países, el objetivo de Shinkansen siempre será entregarte toda la información útil relacionada a la transacción, por lo cual privilegiamos integraciones directas con el la institución financiera donde se recibe el dinero (Creditor FI).
Los datos más relevantes de nuestra notificación son:
- Monto de la transacción
- Número de cuenta del Participante/Creditor
- Institución financiera del Participante
- ID del Participante
- ID único de la transacción
- Moneda
- Nombre del Debtor
- ID del Debtor
- Institución Financiera del Debtor
- Hora de recepción de la transacción
- Hora de envío del mensaje por parte de Shinkansen
- Glosa o Leyenda
- Otra metadata de la transacción, que puede variar por país u institución.
API Reference
En /api/notifications-participant-webhooks puedes encontrar la referencia universal de notificaciones. Los tipos de notificaciones relacionados con payins son:
-
notification_type = "payin": Notificación de entrada de dinero. -
notification_type = "payin_reversal": Notificación de reversa de entrada de dinero.
Ojo con la idempotencia y la validación de firma en las notificaciones
En las notificaciones, tú eres el servidor (mediante tu webhook) y nosotros el cliente que nos conectamos a ese endpoint.
Por ende es crítico que verifiques siempre la firma de Shinkansen en cada mensaje que llegue a tu webhook. Y también es igual de importante que manejes la idempotencia desde el lado servidor, verificando los ids de mensaje para evitar duplicados y respondiéndonos un 409 cuando te hayamos enviado un duplicado
En Shinkansen siempre preferiremos enviar de nuevo un mensaje en caso que no estemos 100% seguros de recibir tu confirmación, y esto puede pasar por razones ajenas al funcionamiento de tu webhook (por ejemplo si hubiera un problema de red que impide que recibamos tu respuesta aunque tú la envíes correctamente)
