Iniciar un Pago (ACH)

Visión General

Este endpoint permite iniciar un pago a través de la infraestructura Bre-B utilizando la API de Passport. Una solicitud exitosa crea el objeto de pago y devuelve los detalles de la transacción, incluyendo su estado y la información del destinatario.

Requisito

Destinatario (ACH) creado exitosamente previamente

Detalles del Endpoint

Parámetro	Descripción
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/payments/ach
Método	POST
Encabezados	Content-Type: application/json, Authorization
Autenticación	Token de Acceso (Bearer Token)

Cuerpo de la Solicitud

Parámetro	Tipo	Obligatario	Descripción
account_id	String	Sí	ID único de la cuenta desde la cual se realizará el pago.
recipient_id	String	Sí	ID único del destinatario ACH que recibirá el pago.
amount	Objeto	Sí	Define el valor y la moneda para la transacción.
value	String	Sí	Valor a transferir.
currency	String	Sí	Moneda de la transacción. Debe ser `"COP"`.
description	String	No	Referencia para el pago: campo de texto libre que permite ingresar cualquier información adicional o personalizada relacionada con la transacción.
type	int	Sí	Código usado para el tipo de transacción en diferentes escenarios según la tabla: Dispersión: Dispersión Cuenta Ahorros: `32` Inscripción CR Cuenta Ahorro: `33` Dispersión Cuenta Corriente: `22` Inscripción CR Cuenta Corriente: `23` Dispersión Depósito Electrónico: `52` Inscripción Depósito Electrónico: `53`

Nota

La notación amount.value hace referencia al campo value dentro del objeto amount.

Ejemplo de Solicitud

curl --location --request POST 'https://api.paas.sandbox.co.passportfintech.com/v1/payments/ach' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \

--data '{

"account_id": "1b095dbd-7d4b-46d5-8807-1d636482e48a",

"recipient_id": "478b5ebe-290a-464b-9acf-352e70e2143d",

"amount": {

"value": "1000.00",

"currency": "COP"

"description": "Payment",

"type": 32

Cuerpo de la Respuesta

Código HTTP: 200 OK
Retorna los datos del pago junto con su ID único.

Ejemplo de Respuesta

{

"amount": {

"value": "1000.00",

"currency": "COP"

"direction": "OUTBOUND",

"status": "PENDING",

"receiver": {

"participant": {

"name": "BANCOLOMBIA",

"identification_number": "007"

"owner": {

"type": "BUSINESS",

"identification_type": "NIT",

"identification_number": "333556747",

"name": "Passport Software SAS"

"account": {

"account_type": "ORDINARY",

"account_number": "8809090909"

}

"account_id": "1b095dbd-7d4b-46d5-8807-1d636482e48a",

"type": "ACH",

"id": "8c2f8977-fddb-41d9-90e1-6c6e8c5634ec",

Importante

El estado del pago será primero PENDING. Una vez que el pago se procese, cambiará a SETTLED.
El id que aparece en la respuesta es el payment_id.
Cuando realizas un pago ACH, este se reflejará en la llamada GET Account. El saldo pendiente (pending_balance)se actualizará. Una vez que el pago ACH sea procesado, disminuirá el saldo pendiente y se actualizará tu saldo disponible (available_balance).

Errores Comunes y Manejo

Código HTTP	Significado	Descripción
400 Bad Request	Datos inválidos	Faltan campos requeridos o contienen valores incorrectos.
401 Unauthorized	Token inválido	El token de acceso ha expirado o es inválido.
403 Forbidden	Acceso denegado	No tienes permisos para crear un pago.
500 Server Error	Error del servidor	Error inesperado al procesar el pago.

Buenas Prácticas

Verifica que los campos account_id y recipient_id correspondan a entidades válidas.
Monitorea el estado del pago (PENDING, SETTLED, etc.) para confirmar su procesamiento.
Implementa manejo de errores en tu integración para gestionar rechazos o demoras en el procesamiento.

Última actualización el