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:

sequenceDiagram
  autonumber
    Shinkansen--)Participante: POST(PayinNotification) via Participant webhook: `/notifications`

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 https://docs.shinkansen.tech/reference/post-notifications-webook 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)