Flujos de excepción

Débito al originador: Flujo de excepción

Durante el proceso de preparación o confirmación del débito la Entidad Participante podría tener inconvenientes técnicos o errores por validación en reglas de negocio. Para este caso, se detalla el flujo de excepción y los servicios que interactuan

sequenceDiagram
autonumber
 participant tb as Entidad Origen
 participant ach as ACH En Línea
 
 tb ->> +ach: Creación de la tx
  Note over ach,tb: POST /v1/money-movement/transfers
  ach -->> +tb: 200 OK
  ach ->> +tb: Llama al prepare debit 
status: pending Note over tb,ach: POST /v1/debits tb -->> +ach: 200 OK tb ->> +tb: Falla la preparación de fondos tb ->>+ach: Confirma error o fallo en preparación del debit
status: failed Note over tb,ach: POST /v1/money-movement/transfers/{id}/status ach -->> +tb: 200 OK ach ->> -tb: Llama al abort del debit
status: aborted Note over ach,tb: POST /v1/debits/{idDebit}/abort tb -->>+ach: 200 OK tb ->>+ach: Confirma abort
status: aborted Note over tb,ach: POST /v1/money-movement/transfers/{id}/status ach -->> +tb: 200 OK ach ->> -tb: Confirma estafo final
status: rejected Note over ach,tb: PUT v1/transfers/{id} tb -->> +ach: 200 OK

Crédito al beneficiario: Flujo de excepción

Durante el proceso de preparación o confirmación del crédito la Entidad Participante podría tener inconvenientes técnicos o errores por validación en reglas de negocio. Para este caso, se detalla el flujo de excepción y los servicios que interactuan

sequenceDiagram
 autonumber
 participant ach as ACH En Línea
 participant tb as Entidad Receptora

 ach ->> tb: Llama al prepare credit 
status: pending note over ach,tb: POST /v1/credits tb -->> ach: 200 OK tb ->> tb: Falla la preparación del crédito tb ->>+ach: Confirma error o fallo en preparación del credit
status: failed Note over tb,ach: POST /v1/money-movement/transfers/{id}/status ach -->> +tb: 200 OK ach ->>+tb: Llama al abort del credit
status: aborted Note over ach,tb: POST /v1/credits/{idCredit}/abort tb -->>+ach: 200 tb ->> +ach: Confirma abort
Status: aborted Note over tb,ach: POST /v1/money-movement/transfers/{id}/status ach -->> +tb: 200 OK ach ->> -tb: Confirma estado final
status: rejected Note over ach,tb: PUT v1/transfers/{id} tb -->> +ach: 200 OK

Las causales de rechazo que se describen a continuación, deben ser enviadas por la Entidad Participante dentro del proceso de excepción para la preparación de débito o del crédito. El código y descripción deberán ser enviados al servicio /v1/money-movement/transfers/{id}/status expuesto por ACH En-línea

Dominio: https://bank.apihub.crt.achcolombia.com.co
POST v1/money-movement/transfers/{id}/status

Campos de entrada

Campo Tipo Validación Longitud Obligatoriedad
meta Objeto N/A N/A SI
requestId cadena UUID que identifica el mensaje. Min 36 - Max 36 SI
version cadena versión del protocolo de mensajería.
valor fijo "1.0.0"
Min 1 Max 15 SI
timestamp fecha Marca de tiempo de envío del mensaje N/A SI
data objeto N/A N/A SI
movementType lista Identificador del schema del flujo transaccional.
Ver Tablas de referencia: "Valores para el campo movementType".
Lista SI
status cadena Estado de la transacción.
Ver Tablas de referencia: "Estados de las transacciones".
Lista SI
creationDateTime fecha Momento en el que se confirma la preparación del débito o crédito N/A SI
debitId cadena Identificador del debit prepare, el banco debe enviar el valor que corresponde a la transferencia. Este valor fue entregado por ACH En-línea en el llamado al endpoint /v1/debits. Min 1 Max 36 COND
Si la acción es un débito se debe informar este campo
coreId cadena Código de error ACH - Columna coreId - Ver tabla "Causales de rechazo retornadas por las Entidades Participantes" Min 1 Max 255 SI
custom objeto N/A N/A COND
Si el status = failed o aborted. Se debe informar este objeto con sus campos.
error subobjeto N/A N/A COND
code cadena Identificador del error en sistema core ACH En-línea. Columna code -
Ver tabla "Causales de rechazo retornadas por las Entidades Participantes".
Min 1 Max 255 COND
description cadena Descripción del error. Columna description -
Ver tabla "Causales de rechazo retornadas por las Entidades Participantes".
Min 1 Max 255 COND

Request ejemplo

curl --location 'https://url_ach/v1/money_movement/transfers/{id}/status' \
--header 'hash: 695ffdf84f0dad0c19e3b8b09a4565246c156d747ffb26149e4c2dc5d3b66ca1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{
    "meta": {
        "requestId": "45cdaa41-b567-4057-9fb7-7240efdfb437",
        "version": "1.0.0",
        "timestamp": "2026-06-15T14:27:28.001"
    },
    "data": {
        "movementType": "P2P-TRANSFER",
        "status": "failed",
        "creationDateTime": "2026-06-15T14:27:28.001",
        "debitId": "deb_03rgXTmRB7aI7jomy",
        "coreId": "B105"
    },
    "custom": {
        "error": {
            "code": "bridge.account-not-found",
            "description": "Cuenta del usuario receptor no existe"
        }
    }
}'

Response confirmación del rechazo

HTTP/1.1 200 OK
Content-Length: 0

Causales de rechazo retornadas por las Entidades Participantes

data.coreId error.code error.description
B001 bridge.entry-timeout Time-Out declarado por el Participante Originador
B002 bridge.entry-timeout Time-Out declarado por el Participante Receptor
B004 bridge.unexpected-error Error tecnico en el SPBVI Originador
B005 bridge.unexpected-error Error tecnico en el SPBVI Receptor
B006 bridge.unexpected-error Error tecnico en el Participante Receptor
B009 bridge.entry-timeout Orden de pago llego al SPBVI Receptor fuera de tiempo
B101 bridge.account-not-found Número de cuenta del Cliente Receptor invalido
B102 bridge.entry-signature-invalid Error en las validaciones de la cuenta del Consumidor financiero Receptor
B103 bridge.transfer-information-invalid Identificación Cliente Receptor errada
B104 bridge.transfer-information-invalid Tipo de medio de pago del Cliente Receptor es errado
B105 bridge.account-not-found Cuenta del usuario receptor no existe
B105 bridge.account-inactive Cuenta del usuario receptor se encuentra inactiva o suspendida
B105 bridge.account-insufficient-balance Cuenta sin fondos suficientes para realizar el movimiento
B107 bridge.account-limit-exceeded Excede el monto máximo del depósito de bajo monto, ordinarios o inclusivos
B108 bridge.account-limit-exceeded Excede el monto máximo del SPBVI
B109 bridge.account-limit-exceeded Excede el monto máximo del Participante Receptor
B110 bridge.intent-signature-invalid Fallo autorizacion en el Participante Receptor
B111 bridge.intent-signature-missing Informacion requerida por el SPBVI Originador esta incompleta
B112 bridge.intent-signature-missing Informacion requerida por el SPBVI Receptor esta incompleta
B113 bridge.entry-duplicated Código QR ya fue usado
B114 bridge.entry-mismatch Código QR no válido
B301 bridge.entry-timeout Time-Out declarado por el SPBVI Originador
B302 bridge.entry-timeout Time-Out declarado por el SPBVI Receptor
Orderarticle 12
Gestión de errores servicios ACH En-línea Anterior