Cómo aceptar la transferencia

Validación de aceptación por el banco destino

Una vez confirmado el débito, ACH En Línea ejecuta controles antifraude sobre la transferencia y contacta a la Entidad Receptora para solicitar la aceptación del pago (prepare credit). Este paso permite a la Entidad Receptora validar la información de la cuenta destino y confirmar que el pago puede ser recibido correctamente.

Durante esta etapa, la Entidad Receptora debe realizar las siguientes validaciones:

  1. Que la cuenta destino exista.
  2. Que la cuenta esté activa y habilitada para recibir pagos.
  3. Que los datos del beneficiario coincidan con los de la cuenta.
  4. Que el monto de la transferencia no supere los límites definidos por la Entidad Receptora.

La notificación de este paso lo realiza la Entidad Participante Receptora a través de la respuesta al llamado orquestado por ACH En Línea para la preparación del crédito.

Aceptación de la transferencia – Paso a paso detallado

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

 ach ->> tb: Llama al prepare credit 
 status: prepare
 Note over tb,ach: POST /v1/credits
tb -->> ach: 200 OK
 tb ->> tb: Validar que
 la cuenta exista
 tb ->> tb: Validar que
 la cuenta esté activa
 tb ->> tb: Validar que
 los datos del benficiario
 coincidan con la cuenta
 tb ->> tb: Validar montos
 y reglas de negocio
 tb ->> tb: Validar otras
reglas de negocio

tb ->> ach: Confirma preparación del credit
status: prepared
    note over tb,ach: POST /v1/money-movement/transfers/{id}/status
    ach -->> +tb: 200 OK

1. ACH En Línea llama a la Entidad Receptora para procesar la operación de preparación del crédito

ACH En Línea inicia el proceso mediante una solicitud POST al endpoint v1/credits de la Entidad Receptora, con la información completa de la transferencia. Estado "prepare"

Dominio: URL Base Entidado
POST /v1/credits

Campos de entrada preparación 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
data objeto N/A N/A SI
creditId cadena Identificador del credit prepare, el banco debe guardar este valor. 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.
Tomar la parte en negrilla.
svgs:20753228543@bancorojo.com.co		 Min 1 Max 34 SI
accountType lista Tipo de cuenta del origen de la transacción.
"VALORES PARA EL TIPO DE CUENTA".
Traducir de la tabla la parte en negrilla.
svgs:20753228543@bancorojo.com.co		 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
accountInformation objeto N/A N/A SI
accountId cadena Número de cuenta del beneficiario de la transacción.
Tomar la parte en negrilla.
svgs:20753228543@bancorojo.com.co		 Min 1 Max 34 SI
accountType lista Tipo de cuenta del beneficiario de la transacción.
Traducir de la tabla la parte en negrilla.
svgs:20753228543@bancorojo.com.co		 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

Request preparación del crédito

curl --location 'https://url_participante/v1/credits' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzdWFyaW8iLCJyb2xlIjoiYXBwLXRlc3QiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.abc123xyz987fakeSignatureOnlyForDemoPurposes' \
--data '{...}'

Data:

{
  "meta": {
    "id": "7d7c8b5c-9e2c-4ed8-a0d1-9a240f8c1002",
    "status": "prepare"
  },
  "data": {
    "creditId": "crd-98ab1234-5678-4def-9876-123456789001",
    "movementType": "B2B-TRANSFER",
    "amountInformation": {
      "amount": 2500000.00,
      "currency": "COP"
    },
    "source": {
      "personType": "LEGAL",
      "document": {
        "number": "900123456",
        "type": "NIT"
      },
      "fullName": "COMERCIALIZADORA ABC SAS",
      "accountInformation": {
        "accountId": "200000123456",
        "accountType": "CCTE",
        "financialInstitutionId": 900123456
      }
    },
    "target": {
      "personType": "LEGAL",
      "document": {
        "number": "901234567",
        "type": "NIT"
      },
      "fullName": "PROVEEDORES XYZ SAS",
      "accountInformation": {
        "accountId": "300000987654",
        "accountType": "CCTE",
        "financialInstitutionId": 901234567
      }
    }
  }
}

Response preparación del crédito

HTTP/1.1 200 OK 
Content-Length: 0

2. Validaciones de reglas de negocio y demás controles

Después de recibir la solicitud de preparación del crédito, La Entidad Participante realiza todas las validaciones de reglas de negocio y controles para garantizar la integridad de la operación. Si alguna validación no se cumple, se rechaza la operación. Si todas se validan correctamente, se procede con la confirmación.

3. Procesar rechazo de la transferencia

Si alguna de las validaciones no se cumple, la Entidad Participante receptora rechaza la operación enviando una solicitud al endpoint v1/money-movement/transfers/{id}/status con el estado "failed".

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

Campos de entrada rechazo

Campos de entrada error en la preparación 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 error en la preparación del 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 transferencia. 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 rechazo

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",
        "creditId": "deb_03rgXTmRB7aI7jomy",
        "coreId": "13456278395678906789"
    },
    "custom": {
        "error": {
            "code": "bridge.account-not-found",
            "description": "1039: Cuenta no encontrada"
        }
    }
}'

Response rechazo preparación crédito

HTTP/1.1 200 OK 
Content-Length: 0

4. Confirma preparación del crédito

La Entidad Receptora envía la confirmación de la preparación del crédito a ACH En Línea enviando la confirmación al servicio expuesto por ACH En-líneav1/money-movement/transfers/{id}/status con el estado "prepared".

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

Campos de entrada confirmación preparación crédito

Campos de entrada confirmación preparación 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 débito (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

Request confirmación de preparación 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": "P2P-TRANSFER",
    "status": "prepared",
    "creationDateTime": "2026-08-20T14:35:20-05:00",
    "creditId": "dbt-3f8d8b9a-1234-4567-89ab-123456789abc",
    "coreId": "CORE-987654321"
  }
}

Response confirmación preparación crédito

HTTP/1.1 200 OK 
Content-Length: 0
Orderarticle 4
Cómo debitar al usuario origen Anterior