Colombia — Descripción general

Colombia (CO) soporta dos proveedores de pago, accesibles bajo el prefijo /v1/co/*:

• Nequi — cobro por notificación push al celular, cobro con QR, dispersión a celulares Nequi y reversos.
• Bre-B — sistema de pagos inmediatos interoperable de Colombia: cobro con QR, dispersión a llaves Bre-B, gestión de destinatarios y resolución de llaves.

El proveedor se elige por la ruta: /v1/co/payin/... y /v1/co/payout/... → Nequi; /v1/co/breb/... → Bre-B.

Montos en pesos enteros

En Colombia todos los montos van en pesos COP enteros. 50000 = $50.000 COP. No envíes centavos ni decimales. La moneda en todas las respuestas es COP.

API key

La autenticación hacia nuestra API usa 4 headers firmados con ECDSA-SHA256 (secp256k1). Ver Firma ECDSA.

La API key debe crearse con region: "CO". Una key de CO solo firma paths /v1/co/*.

Header	Descripción
x-client-id	ID de la API Key del cliente (región CO)
x-timestamp	ISO 8601 actual (±5 min)
x-nonce	String único por request
x-signature	Firma ECDSA-SHA256 en Base64

Índice de endpoints

Todos los endpoints usan autenticación por firma. Montos siempre en pesos COP enteros.

Generales (ambos proveedores)

Método	Path	Descripción
GET	/v1/co/balance	Balance regional CO con desglose por proveedor
GET	/v1/co/transactions	Lista de transacciones (Nequi + Bre-B) para conciliación

Nequi

Método	Path	Descripción
POST	/v1/co/payin/push	Cobro por notificación push
GET	/v1/co/payin/push/{txId}	Estado de un cobro push
POST	/v1/co/payin/push/{txId}/cancel	Cancelar un cobro push pendiente
POST	/v1/co/payin/qr	Cobro con código QR
GET	/v1/co/payin/qr/{txId}	Estado de un cobro QR
POST	/v1/co/payout/disburse	Dispersión a celular Nequi
GET	/v1/co/payout/{externalId}	Estado de una dispersión
POST	/v1/co/payin/{txId}/reversal	Reverso de un cobro
POST	/v1/co/payout/{externalId}/reversal	Reverso de una dispersión

Bre-B

Método	Path	Descripción
POST	/v1/co/breb/payin/qr	Crear QR de cobro (dinámico o estático)
GET	/v1/co/breb/payin/qr/{txId}	Estado del cobro (alias: /v1/co/breb/payin/{txId})
GET	/v1/co/breb/payin/qr/{txId}/detail	Detalle del recurso QR en la red
GET	/v1/co/breb/payin/qrcodes	Listar QRs del comercio (paginado)
POST	/v1/co/breb/payin/qr/decode	Decodificar una cadena EMVCo de QR
DELETE	/v1/co/breb/payin/qr/{txId}	Cancelar/eliminar un QR
POST	/v1/co/breb/recipients	Crear destinatario
GET	/v1/co/breb/recipients	Listar destinatarios (paginado)
GET	/v1/co/breb/recipients/{recipientId}	Consultar destinatario
DELETE	/v1/co/breb/recipients/{recipientId}	Eliminar destinatario
POST	/v1/co/breb/recipients/{recipientId}/resolve	Resolver destinatario contra la red
POST	/v1/co/breb/resolve-key	Resolver una llave (pago único)
POST	/v1/co/breb/validate-key	Validar una llave sin exponer PII
POST	/v1/co/breb/payout	Dispersión a llave / destinatario / resolución
GET	/v1/co/breb/payout/{externalId}	Estado de una dispersión
GET	/v1/co/breb/payments	Listar pagos Bre-B en la red (paginado)

Sandbox vs Producción

Cada cuenta tiene un flag productionEnabled (default false).

Situación	Comportamiento
Cuenta en modo sandbox (status = SANDBOX)	Todas las peticiones van a sandbox. Siempre permitido.
Cuenta activa, productionEnabled = false	Peticiones de producción se rechazan con 403. No se llama al proveedor.
Cuenta activa, productionEnabled = true	Peticiones van a producción.

En sandbox (configuración por defecto) el gateway simula el desenlace automáticamente: al crear la transacción, esta pasa a COMPLETED de inmediato, el balance se mueve igual que en producción y recibes el webhook correspondiente con el campo extra "sandbox": true. La respuesta del POST de creación sigue devolviendo el estado inicial (PENDING / PROCESSING).

Consejo

Flujo recomendado: integra y prueba todo en sandbox → nosotros validamos → activamos productionEnabled → operas en producción sin cambiar tu código.

Nequi vs Bre-B

Aspecto	Nequi	Bre-B
Pay-In	Push (al celular) + QR	QR (dinámico o estático)
Pay-Out	Dispersión por celular	Dispersión a llave, destinatario o resolución
Llaves	—	ID, PHONE, EMAIL, ALPHA, BCODE
Monto máximo	Según límites de tu cuenta	11.500.000 COP por transacción
Reversos	Soportados (pay-in / pay-out)	No disponible

Estados de transacción

Estado	Significado
PENDING	Creada, esperando aprobación / pago
PROCESSING	Dispersión / reverso en curso
COMPLETED	Finalizada con éxito (terminal — mueve el balance)
FAILED	Error definitivo (terminal)
CANCELLED	Cancelada por ti (push cancelado, QR eliminado)
EXPIRED	Venció sin pago (QR / push no aprobado a tiempo)

El estado final siempre se confirma vía webhook. También puedes consultar el estado con GET: si la transacción sigue PENDING, el gateway sincroniza contra el proveedor en esa misma consulta.