- 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
Cómo acreditar al beneficiario
Acreditar el usuario destino
Una vez se confirma el débito de parte de la Entidad Originadora y la Entidad Receptora confirma la preparación del crédito, acreditar al usuario destino es el último paso en el procesamiento de la transferencia. Para realizar esta operación, ACH En Línea llama al endpoint v1/credits/{idCredit}/commit de la Entidad Receptora.
A continuación, se detallan las acciones involucradas, junto con ejemplos prácticos y consideraciones técnicas relevantes.
sequenceDiagram autonumber participant ach as ACH En Línea participant tb as Entidad Receptora ach ->> tb: Llama al commit credit
status: committed note over ach,tb: POST /v1/credits/{idCredit}/commit tb -->> ach: 200 OK tb ->> tb: Realiza el crédito de fondos tb ->>+ach: Confirmación crédito
status: committed Note over tb,ach: POST /v1/money-movement/transfers/{id}/status ach -->> +tb: 200 OK ach ->> -tb: Confirma estado final
status: completed Note over ach,tb: PUT v1/transfers/{id} tb -->> +ach: 200 OK
1. ACH En Línea llama al banco receptor para procesar la operación de commit del crédito
Para ejecutar la acreditación de recursos al beneficiario, ACH En Línea hace solicitud POST al endpoint v1/credits/{idCredit}/commit expuesto por la Entidad Receptora con estado "committed".
Dominio: URL Base Entidad POST v1/credits/{idCredit}/commit Campos de entrada commit del crédito
| Campo | Tipo | Validación | Longitud | Obligatoriedad |
|---|---|---|---|---|
| meta | objeto | N/A | N/A | SI |
| id | cadena | Identificador único de la transacción | Min 1 Max 36 | SI |
| status | cadena | Estado de la transacción. Ver Tablas de referencia: "Estados de las transacciones". | Min 1 Max 8 | SI |
| custom | objeto | N/A | N/A | COND. Si el "status:aborted" se envía el objeto con los campos |
| error | objeto | N/A | N/A | COND. Si el "status:aborted" se envía el objeto con los campos |
| code | cadena | Código de error del rechazo o fallo | Min 1 Max 255 | COND. Si el "status:aborted" se envía el objeto con los campos |
| description | cadena | Descripción del rechazo o fallo | Min 1 Max 255 | COND. Si el "status:aborted" se envía el objeto con los campos |
| data | objeto | N/A | N/A | N/A |
| creditId | cadena | Identificador único del crédito | Min 1 Max 36 | SI |
| movementType | lista | Identificador del schema del flujo transaccional. Ver Tablas de referencia: "Valores para el campo movementType". | Lista | SI |
| amountInformation | objeto | N/A | N/A | SI |
| amount | decimal | Valor de la transacción. 13 enteros, 2 decimales, siempre mayor que cero. El monto máximo por transacción corresponde a 250 MM. | (13,2) | SI |
| currency | lista | Valor por defecto "COP" | Lista | SI |
| source | objeto | N/A | N/A | SI |
| personType | lista | Tipo de persona que originda la transacción. Ver Tablas de referencia: "Valores para el campo personType". | lista | SI |
| document | objeto | N/A | N/A | SI |
| number | cadena | Número de identificación del ordenante del pago. Solo números, si el campo type es NIT. El valor no debe superar los 9 dígitos y sin caracteres especiales. | entero | SI |
| type | lista | Tipo de identificación del ordenante del pago. Ver Tablas de referencia: "Tipos de documento". | lista | SI |
| fullName | cadena | Nombre comercial, se usa para persona jurídica | Min 1 Max 160 | COND Obligatorio si personType es LEGAL |
| firstName | cadena | Primer nombre | Min 1 Max 40 | Obligatorio si personType es NATURAL |
| secondName | cadena | Segundo nombre | Min 1 Max 40 | NO |
| firstLastName | cadena | Primer apellido | Min 1 Max 40 | Obligatorio si personType es NATURAL |
| secondLastName | cadena | segundo apellido | Min 1 Max 40 | NO |
| accountInformation | objeto | N/A | N/A | SI |
| accountId | cadena | Número de cuenta del origen de la transacción. | Min 1 Max 34 | SI |
| accountType | lista | Tipo de cuenta del origen de la transacción. | lista | SI |
| financialInstitutionId | entero | Identificador de la entidad origen. Número NIT sin dígito de verificación y sin caracteres especiales. | Min 1 Max 9 | SI |
| target | objeto | N/A | N/A | SI |
| personType | lista | Tipo de persona beneficiaria de la transacción. Ver Tablas de referencia: "Valores para el campo personType". | lista | SI |
| document | Objeto | N/A | N/A | SI |
| number | cadena | Número de identificación del beneficiario del pago. Solo números, si el campo type es NIT. El valor no debe superar los 9 dígitos y sin caracteres especiales. | entero | SI |
| type | lista | Tipo de identificación del beneficiario del pago. Ver Tablas de referencia: "Tipos de documento". | lista | SI |
| fullName | cadena | Nombre comercial, se usa para persona jurídica | Min 1 Max 160 | COND Obligatorio si personType es LEGAL |
| firstName | cadena | Primer nombre | Min 1 Max 40 | Obligatorio si personType es NATURAL |
| secondName | cadena | Segundo nombre | Min 1 Max 40 | NO |
| firstLastName | cadena | Primer apellido | Min 1 Max 40 | Obligatorio si personType es NATURAL |
| secondLastName | cadena | segundo apellido | Min 1 Max 40 | NO |
| targetSpbviCode | lista | Código del SPBVI receptor | lista | SI |
| alias | objeto | N/A | N/A | SI |
| aliasType | lista | Tipo de llave | lista | SI |
| aliasValue | cadena | Valor de la llave | Min 1 Max 92 | SI |
| accountInformation | objeto | N/A | N/A | SI |
| accountId | cadena | Número de cuenta del beneficiario de la transacción. | Min 1 Max 34 | SI |
| accountType | lista | Tipo de cuenta del beneficiario de la transacción. | lista | SI |
| financialInstitutionId | entero | Identificador de la entidad destino. Número NIT sin dígito de verificación y sin caracteres especiales. | Min 1 Max 9 | SI |
| qr | objeto | N/A | N/A | COND. Se recibe si la transacción corresponde a la lectura de un QR Bre-B |
| qrId | cadena | Identificación del QR obtenido del proceso de lectura | Min 35 Max 35 | COND. Se recibe si la transacción corresponde a la lectura de un QR Bre-B |
Request commit del credito
curl --location 'https://url_participante/v1/credits/{idCredit}/commit' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}' Data:
{
"meta": {
"id": "debf4f70-c30d-4f27-95e6-2f96b91c0001",
"status": "committed"
},
"data": {
"creditId": "9d2f9ed9-7fdb-4d3b-a7bf-8cd1a8e50001",
"movementType": "B2P-TRANSFER",
"amountInformation": {
"amount": 2500000.00,
"currency": "COP"
},
"source": {
"personType": "LEGAL",
"document": {
"number": "900123456",
"type": "NIT"
},
"fullName": "COMERCIALIZADORA ABC SAS",
"accountInformation": {
"accountId": "200012345678",
"accountType": "CCTE",
"financialInstitutionId": 900123456
}
},
"target": {
"personType": "NATURAL",
"document": {
"number": "1020304050",
"type": "CC"
},
"firstName": "CARLOS",
"firstLastName": "RAMIREZ",
"targetSpbviCode": "TFY",
"alias":{
"aliasType": "PHONE",
"aliasValue": "314567890"
},
"accountInformation": {
"accountId": "3001234567",
"accountType": "CAHO",
"financialInstitutionId": 860987654
}
"qr":{
"qrId": "CO.COM.ACH.TRXID6A1AB61E0E8ADAB4BB9"
}
}
}
} Response commit del crédito
HTTP/1.1 200 OK
Content-Length: 0 2. Acreditación de fondos al beneficiario
La Entidad Receptora procesa la acreditación de fondos al beneficiario.
3. Confirmación commit del crédito
La Entidad Receptora procesa confirma el proceso de acreditación. Solicitud POST al endpoint v1/money-movement/transfers/{id}/status con status:committed
Dominio: https://bank.apihub.crt.achcolombia.com.co POST v1/money-movement/transfers/{id}/status Campos de entrada confirmación del commit crédito
Campos de entrada confirmación del commit del crédito (header)
| Campo | Tipo | Validación | Descripción | Obligatoriedad |
|---|---|---|---|---|
| x-hash | String | Min 64 – Máx 64 | Cadena de comprobación de integridad de la trama. Serializar el objeto data y aplicar SHA256. | SI |
Campos de entrada confirmación del commit crédito (Body)
| 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 |
| creditId | cadena | Identificador del credit prepare, el banco debe enviar el valor que corresponde a la transferencias. Este valor fue entregado por ACH En-línea en el llamado al endpoint /v1/credits. | Min 1 Max 36 | COND Si la acción es un débito se debe informar este campo |
| coreId | cadena | Identificador interno del banco para la preparación del débito o crédito. | 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. Ver tabla "VALORES PARA EL CAMPO CODE DEL STATUS". | Min 1 Max 36 | COND |
| description | cadena | Descripción del error. | Min 1 Max 255 | COND |
Request confirmación del commit del crédito
curl --location 'https://url_ach/v1/money-movement/transfers/{id}/status' \
--header 'x-hash: 695ffdf84f0dad0c19e3b8b09a4565246c156d747ffb26149e4c2dc5d3b66ca1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}' {
"meta": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"version": "1.0.0",
"timestamp": "2026-08-20T14:30:00-05:00"
},
"data": {
"movementType": "B2B-TRANSFER",
"status": "committed",
"creationDateTime": "2026-08-20T14:35:20-05:00",
"debitId": "dbt-3f8d8b9a-1234-4567-89ab-123456789abc",
"coreId": "CORE-987654321"
}
} Response confirmación del commit débito
HTTP/1.1 200 OK
Content-Length: 0 4. Notificación estado final
ACH En-línea confirma el estado final de la transferencia tanto a la Entidad Participante Origen como a la Entidad Participante Receptora
Dominio: URL Base entidad PUT /v1/transfers/{id} Campos de entrada notificación estado final
| Campo | Tipo | Validación | Descripción | Obligatoriedad |
|---|---|---|---|---|
| data | objeto | N/A | N/A | SI |
| id | cadena | Identificador único de la transacción | Min 1 Max 36 | SI |
| status | cadena | Estado de la transacción. Ver Tablas de referencia: "Estados de las transacciones". | Para estados finales, los valores serán: completed rejected | SI |
| creationDateTime | fecha | Momento de la respuesta al participante | N/A | SI |
| movementType | lista | Identificador del schema del flujo transaccional. Ver Tablas de referencia: "Valores para el campo movementType". | Lista | SI |
| custom | objeto | objeto | N/A | COND. Si el "status:rejected o aborted" se envía el objeto con los campos |
| error | objeto | objeto | N/A | COND. Si el "status:rejected o aborted" se envía el objeto con los campos |
| code | cadena | Código de error del rechazo o fallo | Min 1 - Max 255 | COND. Si el "status:rejected o aborted" se envía el objeto con los campos |
| description | cadena | Descripción del rechazo o fallo | Min 1 - Max 255 | COND. Si el "status:rejected o aborted" se envía el objeto con los campos |
Request notificación estado final: completed
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"creationDateTime": "2026-08-21T10:15:30-05:00",
"movementType": "P2P-TRANSFER"
}
}
Request notificación estado final: rejected
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "rejected",
"creationDateTime": "2026-08-21T10:15:30-05:00",
"movementType": "P2P-TRANSFER"
}
},
"custom": {
"error": {
"code": "bridge.account-not-found",
"description": "1039: Cuenta no encontrada"
}
},
Response notificación estado final
HTTP/1.1 200 OK
Content-Length: 0 