Iniciar un Pago

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.

Detalles del Endpoint

Parámetro	Descripción
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/payments/breb
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 registrado en Bre-B 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"`.

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

Ejemplo de Solicitud

JSON
    
 
curl --location --request POST'https://api.paas-sandbox.co.passportfintech.com/v1/payments/breb' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
    "account_id": "a9a0e0f7-0263-44ee-911e-d66910f9f5c7", 
    "resolution_id": "1bc138e3-74fc-4b47-a07c-34c197ee53ff",
    "amount": { 
        "value": "100000",
        "currency": "COP"
    }
}'
Copy

Cuerpo de la Respuesta

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

Ejemplo de Respuesta

JSON
    
 
{
    "receiver": {
        "account": {
            "account_number": "88509775041",
            "account_type": "ORDINARY"
        },
        "key": {
            "key_type": "PHONE",
            "key_value": "3975999158"
        },
        "participant": {
            "identification_number": "123456789"
        },
        "owner": {
            "identification_number": "862886878",
            "identification_type": "NIT",
            "type": "BUSINESS",
            "name": "Merchant CWSPZ"
        }
    },
    "direction": "OUTBOUND",
    "qr_code_reference": "",
    "sender": {
        "account": {
            "account_number": "88509775041",
            "account_type": "ORDINARY"
        },
        "participant": {
            "identification_number": "123456789"
        },
        "owner": {
            "identification_number": "862886878",
            "identification_type": "NIT",
            "type": "BUSINESS",
            "name": "Merchant CWSPZ"
        }
    },
    "amount": {
        "value": "100000",
        "currency": "COP"
    },
    "account_id": "a9a0e0f7-0263-44ee-911e-d66910f9f5c7",
    "created_at": "2025-10-10T08:52:05.171Z",
    "resolution_id": "9e5cd615-d2da-43eb-866e-c0026b177c01",
    "updated_at": "2025-10-10T08:52:05.171Z",
    "status": "PROCESSING",
    "id": "0d9f17a1-af37-4e4d-831d-3520b5797aa1"
}
Copy

El estado del pago será primero PENDING. Una vez que el pago se procese, cambiará a SETTLED. Puedes usar los Webhooks para consultar los estados del pago.
El id que aparece en la respuesta es el payment_id.

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