Payouts: Integridad y Tiempos de Espera

Cuando movemos dinero la integridad/consistencia es clave. No queremos tener en un lado la idea de que una transacción falló y en el otro extremo creer que tuvo éxito.

Por eso es clave que todos sepamos quien y cuando determina que una transacción tuvo éxito. Y cuando los otros actores nos enteramos de ese resultado.

¿Quien determina si un payout tiene éxito?

• El PO es el único actor que puede determinar el ✅ éxito o ❌ fallo de una transacción que fue recibida por el PO.
  • Excepcionalmente, Shinkansen podrá determinar el ❌ fallo de una transacción si el PO no puede recibir la instrucción debido a alguna intermitencia prolongada.

¿Cuánto toma el flujo de un payout en ejecutarse?

• Típicamente segundos, según la velocidad de procesamiento del PO (operador de payouts, típicamente el banco desde donde salen los fondos).
  • Pero podría tomar minutos en casos excepcionales (ej: institucion financiera de destino del pago con problemas para aceptarlo).
  • En casos extremadamente excepcionales, podría tomar más de 5 minutos (ej: PO offline después de haber recibido la instrucción de payout).

👍

En la práctica:

Recibirás una respuesta de una transacción de payout en segundos o pocos minutos la mayoría de las veces. Pero debes estar preparado para que algunas transacciones demoren 10-20x más tiempo o incluso que alguna transacción quede pendiente por un tiempo aún mayor. En estos casos excepcionales debes esperar que el actor que está fuera de línea pueda enviar la respuesta (sea el PO, el riel de pagos, la institución financiera destino). Si no esperas, corres el riesgo de asumir que un pago no se realizó cuando sí alcanzó a ser ejecutado antes que ocurriera la intermitencia (o viceversa).

Manejo de errores y tiempos de respuesta

Este diagrama muestra gráficamente el manejo de errores y los tiempos esperados en cada paso:

Cómo se manejan errores en el flujo de payouts

Existen 3 categorías generales de errores en el envío de mensajes o respuestas en Shinkansen:

1. 🔌 Error en conectar: La conexión TCP+TLS con el servidor de destino no se puede establecer.
2. 🐛 Error inesperado del servidor: El servidor de destino responde con un error HTTP 5xx.
3. 💥 Error en mitad de la conexión: La conexión TCP+TLS con el servidor se pudo establecer, pero la respuesta no fue recibida por el cliente (sea por un error del servidor, de la red, o del cliente).

La forma de manejar estos errores varía ligeramente según el caso:

• En el envío del mensaje con transacción (antes de que se ejecute el payout)

  • Si ocurre un 🔌 Error al conectar: 🔄 Reintentar
    • Si los reintentos son infructuosos, como participante puedes 🛑 Abortar la creación de la transacción. Es decir, la transacción no existirá en los registros de Shinkansen.
    • Si los reintentos de Shinkansen hacia el PO son infructuosos, Shinkansen generará la respuesta de ❌ error de la transacción. Es decir, la transacción existió pero su shinkansen_transaction_status será error. El estado de la respuesta (response_status) será error_payment_rail_offline.
  • Si ocurre un 💥 Error en mitad de la conexión o un 🐛 Error inesperado del servidor (ej: error HTTP 5xx): 🔄 Reintentar, usando siempre los mismos message_id y transaction_id del primer intento fallido. (caso contrario se arriesga que el destino haya recibido la transacción y la haya ejecutado).

• En el envío de la respuesta (antes de que se ejecute el payout)

  • Pase lo que pase, el PO y Shinkansen siempre van a 🔄 Reintentar para asegurarse que la respuesta (sea ✅ ok o sea ❌ error) llegue eventualmente a su destino.