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"

Orderarticle 11
Token de autenticación Anterior