API Debito
Endpoint /debit
Este endpoint es invocado por TransfiYa para iniciar el procesamiento de una transferencia. Su propósito es ejecutar una acción de tipo UPLOAD en la nube de TIN y realizar el débito correspondiente en el núcleo bancario.
⚠️ IMPORTANTE: Para evitar el riesgo de ejecutar un doble débito, es fundamental que el banco verifique si la operación de débito ya fue procesada para esa transferencia. Esta verificación puede implementarse validando si una acción de tipo UPLOAD con el mismo identificador (CUS) ya existe en la base de datos del banco.
⚠️ IMPORTANTE: Los objetos de error mostrados en los diagramas son ilustrativos. El contenido específico puede variar según la causa del error. El banco debe enviar el objeto de error correspondiente a la causa real del fallo.
🧭 Pasos generales del flujo
Crear acción de tipo UPLOAD
El banco crea una acción con tipo UPLOAD llamando a POST /v1/action, utilizando como destino el firmante fuente (mainAction.snapshot.source.signer.handle) de la transferencia.
Consultar información local del firmante fuente
Cargar los datos relacionados al firmante fuente desde la base de datos local del banco para validar su existencia, estado y cuenta asociada.
Decidir aceptar o rechazar la transferencia
Con base en la validación previa, el banco decide si se puede continuar con el débito o si debe rechazarse. El estado de la acción será PENDING o REJECT.
Cargar llaves del firmante del banco
Identificar y preparar el keeper del firmante del banco (signer de liquidación) para poder firmar la operación.
Actualizar la acción UPLOAD
El banco actualiza la acción con el campo labels.tx_id que corresponde al identificador de transacción interna del core bancario (PUT /v1/action/:id).
Firmar la acción con el keeper
El banco firma el hash de la acción utilizando su llave privada y genera el objeto IOU (prueba criptográfica del movimiento).
Enviar la acción firmada a TransfiYa
El IOU firmado se envía a POST /v1/action/:id/sendit. TransfiYa valida la firma y marca la acción como COMPLETED.
Llamar al endpoint /continue
Para continuar el flujo, el banco debe invocar POST /v1/transfer/:tx_ref/continue con la acción UPLOAD firmada y finalizada.
CONTINUAR PROCESAMIENTO
Después de procesar la operación de débito en el núcleo bancario, el banco debe invocar el endpoint /v1/transfer/:tx_ref/continue para continuar con el flujo de la transferencia.
La referencia de la transacción en el sistema bancario debe ser almacenada en labels.tx_id. Esta información se utilizará en el proceso de conciliación y será la referencia única para identificar la transacción en el banco en relación con la acción UPLOAD en TransfiYa.
La llamada al endpoint /v1/transfer/:tx_ref/continue debe ejecutarse dentro de los 8 minutos siguientes a la inicialización de la transferencia. De lo contrario, el estado de la transferencia cambiará automáticamente a ERROR.
Flujo Exitoso
TIN Cloud llama al endpoint `/debit` del banco
Se inicia la operación de débito. El payload enviado por TIN contiene la información de la acción principal que se desea ejecutar.
El banco crea una acción `UPLOAD` llamando a `/v1/action`
Se utiliza la información contenida en mainAction para crear la acción. El estado inicial será PENDING y se devolverá un error code 0 si fue exitosa.
El endpoint del banco devuelve a TIN Cloud la acción UPLOAD con estado PENDING en el cuerpo de la respuesta. La respuesta debe incluir el objeto error con código 0 y el mensaje 'Success'
El banco realiza el débito en su Core Bancario
La operación se ejecuta en el core, y si es exitosa, se obtiene una referencia única (tx_id) que será almacenada en la etiqueta labels.tx_id.
El banco firma la acción `UPLOAD` y genera un objeto IOU
El banco firma la acción UPLOAD utilizando las claves asociadas al firmante de origen, es decir, las claves de la cuenta límite del banco, y envía el pagaré firmado (IOU) a través de la llamada POST /v1/action//sendit.
Crear Claims
Cargar Llaves
Crear Claims
Firmar el IOU
Enviar el IOU
Envía el pagaré firmado (IOU), como se explicó en el paso anterior, mediante POST /v1/action//sendit y recibe la acción UPLOAD firmada con estado COMPLETED y el hash de la transacción en el campo labels.
Contiunar
El banco puede invocar el endpoint continue utilizando cualquiera de las siguientes opciones: POST /v1/transfer//continue o POST /v1/transfer//continue.
Esta llamada debe hacerse desde la acción de tipo SEND/REQUEST (denominada mainAction en el paso 1), usando como cuerpo (body) la acción UPLOAD firmada recibida en el paso anterior (con estado COMPLETED y el valor de hash). La respuesta al TIN Cloud debe incluir el objeto error con code: 0 y message: “Success”.
Flujo de Error
TIN Cloud invoca el endpoint `/debit` del banco
TransfiYa realiza una llamada HTTP POST /debit al endpoint configurado por el banco.
El banco crea la acción `UPLOAD`
El banco genera una acción de tipo UPLOAD en su sistema, basada en los datos recibidos en el mainAction.
El banco responde a TIN Cloud
El endpoint del banco responde a TIN Cloud con la acción UPLOAD en estado PENDING dentro del cuerpo de la respuesta.
La respuesta debe contener un objeto error con code: 0 y message: "Success".
El banco procesa el débito en su Core
El banco intenta realizar el débito en su sistema central. En este caso, el Core responde con un ERROR.
El banco debe llamar al endpoint `/v1/transfer/{tx_ref}/continue`
Ante un fallo en el Core, el banco debe invocar el endpoint /v1/transfer/{tx_ref}/continue con los parámetros indicados más abajo.
En caso de error, la acción enviada debe tener el estado ERROR dentro de labels.status, así como un objeto error que incluya code y message.
Además, es obligatorio incluir el action_id de la acción principal SEND/REQUEST al invocar el endpoint continue.
Ejemplo de cuerpo - Error
Código: el campo code debe basarse en la tabla de códigos de error incluida en la documentación técnica del servicio. En caso exitoso, debe enviarse 0.
Mensaje: el campo message debe describir la causa del error según la tabla mencionada. Para una respuesta exitosa, se debe usar "Success".
Conclusión
Una vez completado el proceso de débito (ya sea exitoso o con error), el banco debe llamar al endpoint /v1/transfer/{tx_ref}/continue utilizando la acción UPLOAD o DOWNLOAD, con estado COMPLETED o ERROR. A partir de este punto, TIN Cloud puede continuar con el flujo.
Este paso es obligatorio para que TransfiYa pueda determinar el resultado final de la transferencia.
Las posibilidades a partir del uso del endpoint continue son:
- ✅ Continuar con el procesamiento normal (flujo exitoso)
- ⚠️ Finalizar la transferencia con estado
ERROR - 🔁 Iniciar un flujo de reversa de fondos