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: commit
    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: comited
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

Dominio: URL Base Entidad
POST v1/debits/{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
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.
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 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": "4fa85f64-5717-4562-b3fc-2c963f66afa7",
    "status": "commit"
  },
  "data": {
    "creditId": "crd-660e8400-e29b-41d4-a716-446655440001",
    "movementType": "B2B-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": "LEGAL",
      "document": {
        "number": "901234567",
        "type": "NIT"
      },
      "fullName": "PROVEEDORES XYZ SAS",
      "accountInformation": {
        "accountId": "300045678901",
        "accountType": "CCTE",
        "financialInstitutionId": 901234567
      }
    }
  }
}

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

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/debits. 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": "comited",
    "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

Request notificación estado final

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "creationDateTime": "2026-08-21T10:15:30-05:00",
    "movementType": "P2P-TRANSFER"
  }
}

Response notificación estado final

HTTP/1.1 200 OK
Content-Length: 0
Orderarticle 5
Cómo aceptar la transferencia Anterior