Iniciar un Pago (Bre-B)

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"`.
display_name	String	No	El parámetro se utiliza para mostrar al usuario receptor el nombre o alias del usuario que está enviando los fondos. En el objeto owner (en la respuesta) se presentará la siguiente estructura: "nombre según `display_name` (nombre del merchant)" `"Gustavo Munoz (Merchant I9TOS)"`

Nota

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

El monto máximo para transacciones Bre-B es 11.5 millones de Pesos Colombianos.

Ejemplo de Solicitud

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": "1b095dbd-7d4b-46d5-8807-1d636482e48a", "resolution_id": "039e06fb-5a26-4b8f-9846-023fe8ccc283", "amount": { "value": "1.00", "currency": "COP" }, "display_name" : "Gustavo Munoz" }'

Cuerpo de la Respuesta

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

Ejemplo de Respuesta

{ "status": "PROCESSING", "account_id": "1b095dbd-7d4b-46d5-8807-1d636482e48a", "type": "BREB", "updated_at": "2026-03-09T23:02:06.875Z", "id": "f8d4f5a0-2f35-4f27-a963-6d428f7b8842", "created_at": "2026-03-09T23:02:06.875Z", "resolution_id": "039e06fb-5a26-4b8f-9846-023fe8ccc283", "amount": { "currency": "COP", "value": "1.00" }, "sender": { "owner": { "name": "Gustavo Munoz (Merchant I9TOS)", "identification_type": "NIT", "identification_number": "123450016", "type": "BUSINESS" }, "account": { "account_type": "ORDINARY", "account_number": "866000018" }, "participant": { "identification_number": "890203088" } }, "receiver": { "owner": { "name": "Mi Empresa SAS", "identification_type": "NIT", "identification_number": "123450008", "type": "BUSINESS" }, "key": { "key_type": "ALPHA", "key_value": "@X0LMIDNAGJY6L13LDLZL" }, "account": { "account_type": "ORDINARY", "account_number": "866000012" }, "participant": { "identification_number": "890203088" } }, "direction": "OUTBOUND", "end_to_end_identification": "20260309890203088VIS502154946670531" }

Importante

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.
id que aparece en la respuesta es el payment_id.
Asegúrese de reutilizar el resolution_id cuando vuelva a intentar realizar un pago. Esto es fundamental, ya que garantizamos que solo se creará un pago con el mismo resolution_id. En otras palabras, actúa como una clave de idempotencia, lo que garantiza que no se procesen pagos duplicados.

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