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"

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