- 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
PSE Abono en Línea
PSE Abono en Línea es una funcionalidad que permite a los comercios y empresas recaudadoras recibir pagos en tiempo real, eliminando la necesidad de esperar el procesamiento tradicional por ciclos. Esta capacidad agiliza el proceso de recaudo, mejora la disponibilidad de los fondos y optimiza la experiencia operativa para los actores involucrados. Para habilitar esta funcionalidad, la Entidad Participante Receptora debe implementar el servicio de crédito (preparación y commit)de ACH En-línea, cumpliendo con todos los requisitos técnicos y funcionales establecidos.
A continuación, se describe el paso a paso del flujo de acreditación para Abono en Línea.
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: pending
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. Para PSE Abono en Línea es el CUS de PSE. | 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.Para PSE Abono en Línea "P2B-ABL" | 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 | Para PSE Abono en Línea es un dato genérico | entero | SI |
| type | lista | Para PSE Abono en Línea es un dato genérico | lista | SI |
| fullName | cadena | Nombre comercial, se usa para persona jurídica. Para PSE Abono en Línea es un dato genérico | Min 1 Max 160 | COND Obligatorio si personType es LEGAL |
| firstName | cadena | Primer nombre. Para PSE Abono en Línea es un dato genérico | Min 1 Max 40 | Obligatorio si personType es NATURAL |
| secondName | cadena | Segundo nombre. Para PSE Abono en Línea es un dato genérico | Min 1 Max 40 | NO |
| firstLastName | cadena | Primer apellido. Para PSE Abono en Línea es un dato genérico | Min 1 Max 40 | Obligatorio si personType es NATURAL |
| secondLastName | cadena | Segundo apellido. Para PSE Abono en Línea es un dato genérico | Min 1 Max 40 | NO |
| accountInformation | objeto | N/A | N/A | SI |
| accountId | cadena | Número de cuenta del origen de la transacción. Para PSE Abono en Línea es un dato genérico | Min 1 Max 34 | SI |
| accountType | lista | Tipo de cuenta del origen de la transacción. Para PSE Abono en Línea es un dato genérico | lista | SI |
| financialInstitutionId | entero | Identificador de la entidad origen.Para PSE Abono en Línea es un dato genérico | 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": "pending"
},
"data": {
"creditId": "crd-98ab1234-5678-4def-9876-123456789001",
"movementType": "P2B-ABL",
"amountInformation": {
"amount": 2500000.00,
"currency": "COP"
},
"source": {
"personType": "LEGAL",
"document": {
"number": "XXXXX",
"type": "NIT"
},
"fullName": "BANCO PSE",
"accountInformation": {
"accountId": "XXXXX",
"accountType": "CCTE",
"financialInstitutionId": XXXXXX
}
},
"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 Los demás pasos de la preparación del crédito se deben ejecutar sin excepción, el detalle se podrá encontrará dentro del capítulo "Como aceptar la transferencia"
Acreditar el usuario destino
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
2. 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. Para PSE Abono en Línea es el CUS de PSE. | 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. Para PSE Abono en Línea es "P2B-ABL". | 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. Para PSE Abono en Línea es un dato genérico | lista | SI |
| document | objeto | N/A | N/A | SI |
| number | cadena | Número de identificación del ordenante del pago. Para PSE Abono en Línea es un dato genérico | entero | SI |
| type | lista | Tipo de identificación del ordenante del pago. Para PSE Abono en Línea es un dato genérico | lista | SI |
| fullName | cadena | Nombre comercial, se usa para persona jurídica. Para PSE Abono en Línea es un dato genérico | Min 1 Max 160 | COND Obligatorio si personType es LEGAL |
| firstName | cadena | Primer nombre. Para PSE Abono en Línea es un dato genérico. | Min 1 Max 40 | Obligatorio si personType es NATURAL |
| secondName | cadena | Segundo nombre. Para PSE Abono en Línea es un dato genérico. | Min 1 Max 40 | NO |
| firstLastName | cadena | Primer apellido. Para PSE Abono en Línea es un dato genérico. | Min 1 Max 40 | Obligatorio si personType es NATURAL |
| secondLastName | cadena | segundo apellido. Para PSE Abono en Línea es un dato genérico. | Min 1 Max 40 | NO |
| accountInformation | objeto | N/A | N/A | SI |
| accountId | cadena | Número de cuenta del origen de la transacción. Para PSE Abono en Línea es un dato genérico. | Min 1 Max 34 | SI |
| accountType | lista | Tipo de cuenta del origen de la transacción.Para PSE Abono en Línea es un dato genérico. | lista | SI |
| financialInstitutionId | entero | Identificador de la entidad origen. Para PSE Abono en Línea es un dato genérico. | 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": "committed"
},
"data": {
"creditId": "crd-660e8400-e29b-41d4-a716-446655440001",
"movementType": "P2B-ABL",
"amountInformation": {
"amount": 2500000.00,
"currency": "COP"
},
"source": {
"personType": "LEGAL",
"document": {
"number": "XXXXX",
"type": "NIT"
},
"fullName": "BANCO PSE",
"accountInformation": {
"accountId": "XXXXX",
"accountType": "CCTE",
"financialInstitutionId": XXXXX
}
},
"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 Los demás pasos de la confirmación del crédito se deben ejecutar sin excepción, el detalle se podrá encontrará dentro del capítulo "Como acreditar al beneficiario"
