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", "created_at": "2026-03-10T17:09:36.16Z", "updated_at": "2026-03-10T17:09:36.16Z", "sender": { "participant": { "identification_number": "890203088" }, "owner": { "type": "BUSINESS", "identification_type": "NIT", "identification_number": "123450016", "name": "Merchant I9TOS" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" } } }

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