Payins Transactions

Una 💰🤝Payin Transaction ("transacción de payin") es una transacción iniciada por un participante/cliente de Shinkansen, que busca recaudar dinero en una cuenta bancaria mediante un pago originado típicamente desde otra 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, a quien se le descuenta el dinero enviado.
• Creditor: En el contexto de Payins, es el destinatario del movimiento, es decir, el Participante a quien se le abona el dinero.
• PO: Operador de Pagos, partner de shinkansen, que facilita la ejecución de la transacción.

Desde el punto de vista de quien origina una 💰🤝 Payin Transaction es un ciclo asíncrono de request-response:

sequenceDiagram
  autonumber
    Participante-)Shinkansen: POST(PayinMessage) via Shinkansen endpoint: /messages/payins
    Shinkansen--)Participante: POST(ForwardedPayinResponseMessage) via Participant webhook: .../responses

Tipos de Payin Transactions

Para recaudar fondos desde cuentas bancarias existen múltiples mecanismos en toda latinoamérica. Shinkansen es una solución universal que los clasifica en tres tipos (que corresponden al campo payin_type de la transacción de payin)

Cobro automatizado (automated_payment)

Dependiendo de cada país toma muchos nombres. Débito Inmediato, Domiciliación, Débito Directo, Pago Automático de Cuentas, etc. Pero todos tienen en común que son un mecanismo de cobro automatizado, donde una contraparte ha autorizado al Participante para realizar cargos directamente en su cuenta.

sequenceDiagram
  autonumber
    Participante--)Shinkansen: Obtener previamente autorización para realizar cobros
    Shinkansen--)PO: Obtener previamente autorización para realizar cobros
    Participante-)Shinkansen: POST(PayinMessage) via Shinkansen endpoint: /messages/payins (automated_payment)
    Shinkansen-)PO: Instrucción de cobro
    PO --)Shinkansen: Resultado del cobro
    Shinkansen--)Participante: POST(ForwardedPayinResponseMessage) via Participant webhook: .../responses

Cobro interactivo (interactive_payment)

A través de partners de iniciación de pago puedes cobrar a clientes desde cuentas bancarias en múltiples países, con una única API.

sequenceDiagram
  autonumber
    Participante-)Shinkansen: POST(PayinMessage) via Shinkansen endpoint: /messages/payins (interactive_payment)
    Shinkansen-)PO: Integración con Iniciador de Pagos
    PO-)Shinkansen: Link para pago interactivo
    Shinkansen-)Participante: Link para pago interactivo
    Participante-)PO: Redirecciona a link (o lo envía por correo, etc)
    PO--)Participante:  Redirecciona de vuelta, posterior al pago exitoso o fallido
    PO--)Shinkansen: Notifica resultado
    Shinkansen--)Participante: POST(ForwardedPayinResponseMessage) via Participant webhook: .../responses

Cobro esperado (expected_payment)

Funciona sobre la misma tecnología que las las 💰🔔Payin Notifications, pero con una capa de abstracción/simplicidad adicional, pues Shinkansen se encarga de cuadrar pagos recibidos en una cuenta contra pagos esperados de tus clientes o contrapartes, conciliando automáticamente.

sequenceDiagram
  autonumber
    Participante-)Shinkansen: POST(PayinMessage) via Shinkansen endpoint: /messages/payins (expected_payment)
    Shinkansen-)PO: Integración con Creditor FI
    Contraparte --) PO: Realiza transferencia a la institución financiera
    PO --) Shinkansen: Notifica la transferencia
    Shinkansen --) Shinkansen: Concilia el pago versus expected payments pendientes
    Shinkansen--)Participante: POST(ForwardedPayinResponseMessage) via Participant webhook: .../responses

Los cobros esperados pueden tener fecha de expiración, tras lo cual Shinkansen generará una respuesta de error y eliminará el cobro esperado de la lista pendiente de conciliar.

API Reference

En https://docs.shinkansen.tech/reference/postpayinmessage puedes encontrar la referencia para enviar un mensaje con transacciones de payins.

Y en https://docs.shinkansen.tech/reference/postresponsewebookpayins puedes encontrar la referencia para el webhook que recibirás como respuesta.

Y en https://docs.shinkansen.tech/docs/simulated-bank puedes encontrar como hacer pruebas en desarrollo.