- Cómo enviar cuenta a cuenta
- Cómo debitar al usuario origen
- Cómo aceptar la transferencia
- Cómo acreditar al beneficiario
- Notificación estado final
- Como consultar una transferencia
- Gestión de errores servicios ACH En-línea
- Flujos de excepción
- Tablas de referencia
- Token de autenticación
- PSE Abono en Línea
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": "307"
},
"custom": {
"error": {
"code": "bridge.account-not-found",
"description": "Cuenta inactiva"
}
}
}'
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 |
|---|---|---|
| 334 | bridge.account-inactive | Cuenta inactiva |
| 335 | bridge.account-not-found | Cuenta embargada |
| 336 | bridge.account-not-found | Cuenta cancelada |
| 337 | bridge.account-not-found | Cuenta no existe |
| 339 | bridge.account-inactive | Cuenta no asignada |
| 340 | bridge.account-inactive | Cuenta saldada |
| 341 | bridge.account-inactive | Numero de identificación errado |
| 307 | bridge.account-inactive | Identificacion no coincide con la cuenta |
| 338 | bridge.entry-rejected | Cuenta o Deposito Electronico No Habilitado para recibir transacciones |
| 342 | bridge.account-insufficient-balance | Fondos insuficientes |
| 313 | bridge.account-limit-exceeded | Topes transaccionales excedidos |
| 316 | bridge.entry-duplicated | Ya existe una transaccion registrada con el mismo id |
| 332 | bridge.entry-timeout | Timeout |
| 322 | bridge.fraud-detected | Transaccion rechazada por prevencion fraude en Banco |
| 332 | bridge.ledger-failed | Error interno en el banco |
| 314 | bridge.core-unreachable | Banco fuera de servicio por mantenimiento o indisponibilidad |
| 332 | bridge.unexpected-core-error | Error no identificado en el banco |
| 332 | bridge.unexpected-error | Error inesperado durante el procesamiento de transaccion |
| 316 | bridge.core-access-invalid | Error de acceso invalido en banco |
| 316 | bridge.transfer-information-invalid | La informacion de la transferencia no es valida |
