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 | Restricciones | 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
11
11
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" }}'Cuerpo de la Respuesta
- Código HTTP: 200 OK
- Retorna los datos del pago junto con su ID único.
Ejemplo de Respuesta
48
48
{ "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"}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.
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_idyrecipient_idcorrespondan 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.