- Cómo enviar a Bre-b
- Cómo debitar al usuario origen
- Cómo aceptar la transferencia
- Cómo acreditar al beneficiario
- Notificación estado final
- Como enviar marcas de tiempo
- Cómo reintentar créditos
- Lineamientos del flujo regulatorio
- Errores del MOL
- Como consultar una transferencia
- Gestión de errores servicios ACH En-línea
- Flujos de excepción
- Tablas de referencia
- Token de autenticación
- Contexto Integración
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 |
