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`

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

Ejemplo de Solicitud

JSON
    
xxxxxxxxxx
 
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
}'
Copy

Cuerpo de la Respuesta

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

Ejemplo de Respuesta

JSON
    
xxxxxxxxxx
 
{
    "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"
        }
    }
}
Copy

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