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/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": "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 Notificación estado final Siguiente