> ## Documentation Index
> Fetch the complete documentation index at: https://transfiya.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  ⚠️ **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.
</Warning>

<Warning>
  ⚠️ **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.
</Warning>

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant tfy as TransfiYa
    participant bridge as Bank Bridge
    participant core as Bank Core

    %% Flujo exitoso
    tfy->>bridge: POST /debit (mainAction)
    bridge->>bridge: Crear acción UPLOAD
    bridge-->>tfy: HTTP 200 OK
    tfy-->>bridge: HTTP 200 OK

    bridge->>bridge: Validar firmante y datos
    bridge->>core: Debitar cuenta bancaria
    core-->>bridge: tx_id

    bridge->>bridge: Actualizar acción con tx_id
    bridge-->>tfy: HTTP 200 OK

    bridge->>bridge: Crear y firmar IOU
    bridge->>tfy: POST /sendit (IOU)
    tfy-->>bridge: HTTP 200 OK

    bridge->>tfy: POST /continue

    note over tfy,bridge: Fin del flujo exitoso

    %% Flujo de error 1 - creación de acción UPLOAD falla
    alt Error: creación UPLOAD falla
        bridge-->>tfy: HTTP 400 Validation error
        tfy-->>bridge: Retornar /debit sin cambios
    end

    %% Flujo de error 2 - débito rechazado en core
    alt Error: core rechaza débito
        core-->>bridge: error de negocio
        bridge->>bridge: Marcar acción como ERROR
        bridge->>tfy: POST /continue con error
    end

    %% Flujo de error 3 - fallo en /sendit
    alt Error: falla en envío de IOU
        bridge->>tfy: POST /sendit (IOU)
        tfy-->>bridge: HTTP 400
        bridge->>tfy: POST /continue con error
    end
```

## 🧭 Pasos generales del flujo

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`).
  </Step>

  <Step title="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).
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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.

<Warning title="IMPORTANTE">
  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.
</Warning>

<Info title="IMPORTANTE">
  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`.
</Info>

## Flujo Exitoso

<Steps>
  <Step title="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.

    ```json theme={null}
    {
      "source": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
      "target": "$573148514092",
      "amount": "200.00",
      "symbol": "$tin",
      "labels": {
        "hash": "PENDING",
        "type": "SEND",
        "domain": "tin",
        "flowId": "Ss84Vb42kGa6gPV57",
        "status": "PENDING",
        "tx_ref": "Ss84Vb42kGa6gPV57",
        "created": "2022-08-04T07:08:41-05:00",
        "updated": "2022-08-04T07:08:41-05:00",
        "description": "DEV - REQUEST trx 01",
        "sourceChannel": "APP",
        "deviceFingerPrint": {
          "city": "Bogotá",
          "hash": "26fff5af6441f8e15a71e8d62c361714484b1b308c99e8eb68ca85e2a7e0dc58",
          "model": "Huawei Mate 20 Pro",
          "country": "Colombia",
          "operator": "Bharti Airtel Limited",
          "SIMCardId": "8991101200003204510",
          "ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
          "mobileDevice": "990000862471854"
        }
      },
      "snapshot": {
        "source": {
          "signer": {
            "handle": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
            "labels": {
              "type": "PERSON",
              "email": "Florida_Sawayn@yahoo.com",
              "mobile": "573123224352",
              "created": "2022-06-10T09:50:25-05:00",
              "bankName": "bancosanti",
              "lastName": "Sanford",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "firstName": "Cale",
              "description": "Investor",
              "proprietary": "CC",
              "identification": "1231231",
              "bankAccountType": "SVGS",
              "routerReference": "$bancosanti",
              "bankAccountNumber": "689",
              "countryOfResidence": "CO"
            }
          },
          "wallet": {
            "handle": "$573123224352",
            "labels": {
              "type": "PERSON",
              "created": "2022-06-10T09:54:42-05:00",
              "updated": "2022-06-10T09:54:42-05:00",
              "channelSms": "573123224352"
            },
            "signer": ["wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U"]
          }
        },
        "symbol": {
          "signer": {
            "handle": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d",
            "labels": {
              "created": "2018-10-19T20:23:22.041Z",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            }
          },
          "wallet": {
            "handle": "$tin",
            "labels": {
              "type": "SYMBOL",
              "created": "2018-10-19T20:22:48.350Z",
              "updated": "1970-01-01T15:38:20-05:00",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            },
            "signer": ["wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"],
            "default": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"
          }
        },
        "target": {
          "signer": {
            "labels": {}
          },
          "wallet": {
            "handle": "$573148514092",
            "labels": {
              "type": "PERSON",
              "created": "2022-06-15T11:17:19-05:00",
              "updated": "2022-06-15T11:17:19-05:00"
            },
            "signer": ["wgsAjQJDaehqmZouBHLaiN7DTZBPN5TyFT"]
          }
        }
      },
      "action_id": "5c2d931d-67c6-41b3-ae08-1f42a3d094a0",
      "error": {
        "code": 0,
        "message": "Success"
      },
      "id": "5c2d931d-67c6-41b3-ae08-1f42a3d094a0"
    }
    ```
  </Step>

  <Step title="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.

    ```json theme={null}
    {
        "source": bankKey.signer,//Bank Signer
        "target": mainAction.snapshot.source.signer.handle,
        "symbol": mainAction.symbol,
        "amount": mainAction.amount,
        "labels": {
          "type": "UPLOAD",
          "deviceFingerPrint": mainAction.labels.deviceFingerPrint,
          "domain": mainAction.labels.domain,
          "tx_ref": mainAction.labels.tx_ref
        }
     }
    ```
  </Step>

  <Step title="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'">
    ```json theme={null}
    {
      "source": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr",
      "target": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
      "amount": "200.00",
      "symbol": "$tin",
      "labels": {
        "hash": "PENDING",
        "type": "UPLOAD",
        "domain": "tin",
        "status": "PENDING",
        "tx_ref": "Ss84Vb42kGa6gPV57",
        "created": "2022-08-04T07:05:26-05:00",
        "updated": "2022-08-04T07:05:26-05:00",
        "description": "",
        "deviceFingerPrint": {
          "city": "Bogotá",
          "hash": "26fff5af6441f8e15a71e8d62c361714484b1b308c99e8eb68ca85e2a7e0dc58",
          "model": "Huawei Mate 20 Pro",
          "country": "Colombia",
          "operator": "Bharti Airtel Limited",
          "SIMCardId": "8991101200003204510",
          "ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
          "mobileDevice": "990000862471854"
        }
      },
      "snapshot": {
        "source": {
          "signer": {
            "handle": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr",
            "labels": {
              "type": "TROUPE",
              "created": "2022-06-10T10:46:35-05:00",
              "bankName": "bancosanti",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "description": "Bank",
              "routerReference": "$bancosanti",
              "bankAccountNumber": "160101"
            }
          },
          "wallet": {
            "handle": "$bancosanti",
            "labels": {
              "url": "http://bancosanti.com",
              "type": "TROUPE",
              "domain": "tin",
              "created": "2022-06-09T14:55:38-05:00",
              "updated": "2022-08-04T07:03:45-05:00",
              "bankName": "bancosanti",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "entityType": "Bancos",
              "limitAlert": "5000000",
              "routerAction": "https://3ad0-186-170-222-190.ngrok.io/action",
              "routerStatus": "https://3ad0-186-170-222-190.ngrok.io/status",
              "routerUpload": "https://3ad0-186-170-222-190.ngrok.io/debit",
              "routerDownload": "https://3ad0-186-170-222-190.ngrok.io/credit",
              "routerAuthMethod": "NONE",
              "routerAuthParams": {}
            },
            "signer": [
              "wcyq8otjHN789tVTMQ4Xx7Dyk7GB9FUsUj",
              "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr"
            ],
            "default": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr"
          }
        },
        "symbol": {
          "signer": {
            "handle": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d",
            "labels": {
              "created": "2018-10-19T20:23:22.041Z",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            }
          },
          "wallet": {
            "handle": "$tin",
            "labels": {
              "type": "SYMBOL",
              "created": "2018-10-19T20:22:48.350Z",
              "updated": "1970-01-01T15:38:20-05:00",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            },
            "signer": ["wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"],
            "default": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"
          }
        },
        "target": {
          "signer": {
            "handle": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
            "labels": {
              "type": "PERSON",
              "email": "Florida_Sawayn@yahoo.com",
              "mobile": "573123224352",
              "created": "2022-06-10T09:50:25-05:00",
              "bankName": "bancosanti",
              "lastName": "Sanford",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "firstName": "Cale",
              "description": "Investor",
              "proprietary": "CC",
              "identification": "1231231",
              "bankAccountType": "SVGS",
              "routerReference": "$bancosanti",
              "bankAccountNumber": "689",
              "countryOfResidence": "CO"
            }
          },
          "wallet": {
            "handle": "$573123224352",
            "labels": {
              "type": "PERSON",
              "created": "2022-06-10T09:54:42-05:00",
              "updated": "2022-06-10T09:54:42-05:00",
              "channelSms": "573123224352"
            },
            "signer": ["wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U"]
          }
        }
      },
      "action_id": "5954ac04-b4db-4c6f-86f6-43df30f6bacb",
      "error": {
        "code": 0,
        "message": "Success"
      }
    }
    ```
  </Step>

  <Step title="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`.

    ```json theme={null}
    {
      "labels": {
        "tx_id": "BANKING_CORE_TX_ID"
      }
    }
    ```

    ```json theme={null}
    {
      "source": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr",
      "target": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
      "amount": "200.00",
      "symbol": "$tin",
      "labels": {
        "hash": "PENDING",
        "type": "UPLOAD",
        "domain": "tin",
        "status": "PENDING",
        "tx_ref": "Ss84Vb42kGa6gPV57",
        "created": "2022-08-04T07:05:26-05:00",
        "updated": "2022-08-04T07:05:26-05:00",
        "description": "",
        "deviceFingerPrint": {
          "city": "Bogotá",
          "hash": "26fff5af6441f8e15a71e8d62c361714484b1b308c99e8eb68ca85e2a7e0dc58",
          "model": "Huawei Mate 20 Pro",
          "country": "Colombia",
          "operator": "Bharti Airtel Limited",
          "SIMCardId": "8991101200003204510",
          "ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
          "mobileDevice": "990000862471854"
        },
        "tx_id": 3
      },
      "snapshot": {
        "source": {
          "signer": {
            "handle": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr",
            "labels": {
              "type": "TROUPE",
              "created": "2022-06-10T10:46:35-05:00",
              "bankName": "bancosanti",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "description": "Bank",
              "routerReference": "$bancosanti",
              "bankAccountNumber": "160101"
            }
          },
          "wallet": {
            "handle": "$bancosanti",
            "labels": {
              "url": "http://bancosanti.com",
              "type": "TROUPE",
              "domain": "tin",
              "created": "2022-06-09T14:55:38-05:00",
              "updated": "2022-08-04T07:03:45-05:00",
              "bankName": "bancosanti",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "entityType": "Bancos",
              "limitAlert": "5000000",
              "routerAction": "https://3ad0-186-170-222-190.ngrok.io/action",
              "routerStatus": "https://3ad0-186-170-222-190.ngrok.io/status",
              "routerUpload": "https://3ad0-186-170-222-190.ngrok.io/debit",
              "routerDownload": "https://3ad0-186-170-222-190.ngrok.io/credit",
              "routerAuthMethod": "NONE",
              "routerAuthParams": {}
            },
            "signer": [
              "wcyq8otjHN789tVTMQ4Xx7Dyk7GB9FUsUj",
              "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr"
            ],
            "default": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr"
          }
        },
        "symbol": {
          "signer": {
            "handle": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d",
            "labels": {
              "created": "2018-10-19T20:23:22.041Z",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            }
          },
          "wallet": {
            "handle": "$tin",
            "labels": {
              "type": "SYMBOL",
              "created": "2018-10-19T20:22:48.350Z",
              "updated": "1970-01-01T15:38:20-05:00",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            },
            "signer": ["wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"],
            "default": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"
          }
        },
        "target": {
          "signer": {
            "handle": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
            "labels": {
              "type": "PERSON",
              "email": "Florida_Sawayn@yahoo.com",
              "mobile": "573123224352",
              "created": "2022-06-10T09:50:25-05:00",
              "bankName": "bancosanti",
              "lastName": "Sanford",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "firstName": "Cale",
              "description": "Investor",
              "proprietary": "CC",
              "identification": "1231231",
              "bankAccountType": "SVGS",
              "routerReference": "$bancosanti",
              "bankAccountNumber": "689",
              "countryOfResidence": "CO"
            }
          },
          "wallet": {
            "handle": "$573123224352",
            "labels": {
              "type": "PERSON",
              "created": "2022-06-10T09:54:42-05:00",
              "updated": "2022-06-10T09:54:42-05:00",
              "channelSms": "573123224352"
            },
            "signer": ["wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U"]
          }
        }
      },
      "action_id": "5954ac04-b4db-4c6f-86f6-43df30f6bacb",
      "error": {
        "code": 0,
        "message": "Success"
      },
      "id": "5954ac04-b4db-4c6f-86f6-43df30f6bacb"
    }
    ```
  </Step>

  <Step title="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/{uploadAction_id}/sendit.
  </Step>

  <Step title="Crear Claims">
    ```json theme={null}
    {
      "source": uploadAction.snapshot.source.signer.handle, //Bank Signer Handle
      "target": uploadAction.snapshot.target.signer.handle, //User Signer Handle
      "symbol": uploadAction.snapshot.symbol.signer.handle, //Symbol Signer Handle
      "amount": uploadAction.amount,
      "domain": "tin",
      "expiry": "${expirationTime}" // currentTime + 1 minute in ISO8601 format, example "2021-11-03T13:50:41.431Z"
    }
    ```
  </Step>

  <Step title="Cargar Llaves">
    ```json theme={null}
    keys = [
      {
        "public": "BANK_PUBLIC_KEY",
        "secret": "BANK_SECRET_KEY",
        "scheme": "BANK_KEEPER_SCHEME",
        "signer": "BANK_SIGNER_HANDLE"
      }
    ]
    ```
  </Step>

  <Step title="Crear Claims">
    ```json theme={null}
    {
      "source": uploadAction.snapshot.source.signer.handle, //Bank Signer Handle
      "target": uploadAction.snapshot.target.signer.handle, //User Signer Handle
      "symbol": uploadAction.snapshot.symbol.signer.handle, //Symbol Signer Handle
      "amount": uploadAction.amount,
      "domain": "tin",
      "expiry": "${expirationTime}" // currentTime + 1 minute in ISO8601 format, example "2021-11-03T13:50:41.431Z"
    }
    ```
  </Step>

  <Step title="Firmar el IOU">
    ```json theme={null}
    {
      "hash": {
        "types": "sha256:sha256",
        "steps": "stringify:data",
        "value": "263b8cebe62473ad9bb6ca6a92db7e5c8b16492b359515375ae8bf05094c3a14"
      },
      "data": {
        "source": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr", //Bank Signer
        "target": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U", //User signer
        "symbol": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d",
        "amount": "200.00",
        "domain": "tin",
        "expiry": "2022-08-04T14:15:04.189Z",
        "random": "7f19c57edb362726da0c"
      },
      "meta": {
        "signatures": [
          {
            "scheme": "ecdsa-ed25519",
            "signer": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr", //Bank Signer
            "public": "046a23ccc4585f6105a199ec5202d4019d589a3370b52a783268016751e2db9281371fe2cc28901e24ece5d47b29ed0b7d741d17dd8221b9735bf922dc40a621b1", //Bank signer public key
            "string": "3043021f17472d781f6873203671439fc1277b085971f38928da9165ab4f386117966302200c518cfef98841aa353eb0832a87eca44929df7d2d475c70203effca27ca6241",
            "linker": "sha256:ripemd160"
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Enviar el IOU">
    Envía el pagaré firmado (IOU), como se explicó en el paso anterior, mediante POST /v1/action/{uploadAction_id}/sendit y recibe la acción UPLOAD firmada con estado COMPLETED y el hash de la transacción en el campo labels.

    ```json theme={null}
    {
      "source": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr",
      "target": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
      "amount": "200.00",
      "symbol": "$tin",
      "labels": {
        "hash": "3ca7af8dcccaed3f7f1821456eaece8746310b566687401ae11c0b22624874a9",
        "type": "UPLOAD",
        "tx_id": 3,
        "domain": "tin",
        "status": "COMPLETED",
        "tx_ref": "Ss84Vb42kGa6gPV57",
        "created": "2022-08-04T07:05:26-05:00",
        "updated": "2022-08-04T07:05:27-05:00",
        "description": "",
        "deviceFingerPrint": {
          "city": "Bogotá",
          "hash": "26fff5af6441f8e15a71e8d62c361714484b1b308c99e8eb68ca85e2a7e0dc58",
          "model": "Huawei Mate 20 Pro",
          "country": "Colombia",
          "operator": "Bharti Airtel Limited",
          "SIMCardId": "8991101200003204510",
          "ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
          "mobileDevice": "990000862471854"
        },
        "iouHash": "9e68de4bf2095ca0328252e6cb66fe957ac0b62ecde0f74b8ddc6314717c07a1"
      },
      "snapshot": {
        "source": {
          "signer": {
            "handle": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr",
            "labels": {
              "type": "TROUPE",
              "created": "2022-06-10T10:46:35-05:00",
              "bankName": "bancosanti",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "description": "Bank",
              "routerReference": "$bancosanti",
              "bankAccountNumber": "160101"
            }
          },
          "wallet": {
            "handle": "$bancosanti",
            "labels": {
              "url": "http://bancosanti.com",
              "type": "TROUPE",
              "domain": "tin",
              "created": "2022-06-09T14:55:38-05:00",
              "updated": "2022-08-04T07:03:45-05:00",
              "bankName": "bancosanti",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "entityType": "Bancos",
              "limitAlert": "5000000",
              "routerAction": "https://3ad0-186-170-222-190.ngrok.io/action",
              "routerStatus": "https://3ad0-186-170-222-190.ngrok.io/status",
              "routerUpload": "https://3ad0-186-170-222-190.ngrok.io/debit",
              "routerDownload": "https://3ad0-186-170-222-190.ngrok.io/credit",
              "routerAuthMethod": "NONE",
              "routerAuthParams": {}
            },
            "signer": [
              "wcyq8otjHN789tVTMQ4Xx7Dyk7GB9FUsUj",
              "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr"
            ],
            "default": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr"
          }
        },
        "symbol": {
          "signer": {
            "handle": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d",
            "labels": {
              "created": "2018-10-19T20:23:22.041Z",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            }
          },
          "wallet": {
            "handle": "$tin",
            "labels": {
              "type": "SYMBOL",
              "created": "2018-10-19T20:22:48.350Z",
              "updated": "1970-01-01T15:38:20-05:00",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            },
            "signer": ["wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"],
            "default": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"
          }
        },
        "target": {
          "signer": {
            "handle": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
            "labels": {
              "type": "PERSON",
              "email": "Florida_Sawayn@yahoo.com",
              "mobile": "573123224352",
              "created": "2022-06-10T09:50:25-05:00",
              "bankName": "bancosanti",
              "lastName": "Sanford",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "firstName": "Cale",
              "description": "Investor",
              "proprietary": "CC",
              "identification": "1231231",
              "bankAccountType": "SVGS",
              "routerReference": "$bancosanti",
              "bankAccountNumber": "689",
              "countryOfResidence": "CO"
            }
          },
          "wallet": {
            "handle": "$573123224352",
            "labels": {
              "type": "PERSON",
              "created": "2022-06-10T09:54:42-05:00",
              "updated": "2022-06-10T09:54:42-05:00",
              "channelSms": "573123224352"
            },
            "signer": ["wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U"]
          }
        }
      },
      "action_id": "5954ac04-b4db-4c6f-86f6-43df30f6bacb",
      "error": {
        "code": 0,
        "message": "Success"
      },
      "id": "5954ac04-b4db-4c6f-86f6-43df30f6bacb"
    }
    ```
  </Step>

  <Step title="Contiunar">
    El banco puede invocar el endpoint continue utilizando cualquiera de las siguientes opciones:
    POST /v1/transfer/{mainAction_id}/continue o POST /v1/transfer/{txRef}/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".

    ```json theme={null}
    {
      "source": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr",
      "target": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
      "amount": "200.00",
      "symbol": "$tin",
      "labels": {
        "hash": "3ca7af8dcccaed3f7f1821456eaece8746310b566687401ae11c0b22624874a9",
        "type": "UPLOAD",
        "tx_id": 3,
        "domain": "tin",
        "status": "COMPLETED",
        "tx_ref": "Ss84Vb42kGa6gPV57",
        "created": "2022-08-04T07:05:26-05:00",
        "updated": "2022-08-04T07:05:27-05:00",
        "description": "",
        "deviceFingerPrint": {
          "city": "Bogotá",
          "hash": "26fff5af6441f8e15a71e8d62c361714484b1b308c99e8eb68ca85e2a7e0dc58",
          "model": "Huawei Mate 20 Pro",
          "country": "Colombia",
          "operator": "Bharti Airtel Limited",
          "SIMCardId": "8991101200003204510",
          "ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
          "mobileDevice": "990000862471854"
        },
        "iouHash": "9e68de4bf2095ca0328252e6cb66fe957ac0b62ecde0f74b8ddc6314717c07a1"
      },
      "snapshot": {
        "source": {
          "signer": {
            "handle": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr",
            "labels": {
              "type": "TROUPE",
              "created": "2022-06-10T10:46:35-05:00",
              "bankName": "bancosanti",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "description": "Bank",
              "routerReference": "$bancosanti",
              "bankAccountNumber": "160101"
            }
          },
          "wallet": {
            "handle": "$bancosanti",
            "labels": {
              "url": "http://bancosanti.com",
              "type": "TROUPE",
              "domain": "tin",
              "created": "2022-06-09T14:55:38-05:00",
              "updated": "2022-08-04T07:03:45-05:00",
              "bankName": "bancosanti",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "entityType": "Bancos",
              "limitAlert": "5000000",
              "routerAction": "https://3ad0-186-170-222-190.ngrok.io/action",
              "routerStatus": "https://3ad0-186-170-222-190.ngrok.io/status",
              "routerUpload": "https://3ad0-186-170-222-190.ngrok.io/debit",
              "routerDownload": "https://3ad0-186-170-222-190.ngrok.io/credit",
              "routerAuthMethod": "NONE",
              "routerAuthParams": {}
            },
            "signer": [
              "wcyq8otjHN789tVTMQ4Xx7Dyk7GB9FUsUj",
              "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr"
            ],
            "default": "wNbBi3CcZzggFJ9dvDWk35srVGgaAVLzUr"
          }
        },
        "symbol": {
          "signer": {
            "handle": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d",
            "labels": {
              "created": "2018-10-19T20:23:22.041Z",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            }
          },
          "wallet": {
            "handle": "$tin",
            "labels": {
              "type": "SYMBOL",
              "created": "2018-10-19T20:22:48.350Z",
              "updated": "1970-01-01T15:38:20-05:00",
              "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            },
            "signer": ["wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"],
            "default": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d"
          }
        },
        "target": {
          "signer": {
            "handle": "wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U",
            "labels": {
              "type": "PERSON",
              "email": "Florida_Sawayn@yahoo.com",
              "mobile": "573123224352",
              "created": "2022-06-10T09:50:25-05:00",
              "bankName": "bancosanti",
              "lastName": "Sanford",
              "bankBicfi": "9574",
              "createdBy": "A16iU3t38Tygr70uO1qf",
              "firstName": "Cale",
              "description": "Investor",
              "proprietary": "CC",
              "identification": "1231231",
              "bankAccountType": "SVGS",
              "routerReference": "$bancosanti",
              "bankAccountNumber": "689",
              "countryOfResidence": "CO"
            }
          },
          "wallet": {
            "handle": "$573123224352",
            "labels": {
              "type": "PERSON",
              "created": "2022-06-10T09:54:42-05:00",
              "updated": "2022-06-10T09:54:42-05:00",
              "channelSms": "573123224352"
            },
            "signer": ["wLd9MEASjQQTYywoXnDNwTRpgwiDfyHj6U"]
          }
        }
      },
      "action_id": "5954ac04-b4db-4c6f-86f6-43df30f6bacb",
      "error": {
        "code": 0,
        "message": "Success"
      },
      "id": "5954ac04-b4db-4c6f-86f6-43df30f6bacb"
    }
    ```
  </Step>
</Steps>

## Flujo de Error

<Step title="TIN Cloud invoca el endpoint `/debit` del banco">
  TransfiYa realiza una llamada HTTP `POST /debit` al endpoint configurado por el banco.
</Step>

<Step title="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`.
</Step>

<Step title="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"`.
</Step>

<Step title="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**.
</Step>

<Step title="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.
</Step>

<Info>
  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`.
</Info>

### Ejemplo de cuerpo - Error

```json theme={null}
{
  "action_id": "UPLOAD action_id",
  "source": "wsigner_bank",
  "target": "wsource_signer_user",
  "symbol": "$tin",
  "amount": "AMOUNT",
  "labels": {
    "tx_ref": "XsC3VbB2kGa6gPS51",
    "type": "UPLOAD",
    "status": "ERROR"
  },
  "error": {
    "code": "described below",
    "message": "described below"
  }
}
```

<Info>
  **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"`.
</Info>

## 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.

<Info>
  Este paso es obligatorio para que TransfiYa pueda determinar el resultado final de la transferencia.
</Info>

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