Consultar balance

Retorna el saldo disponible del usuario. Para COP, USD y MXN se usa GET /balance/ con el parámetro currency.

Balance por moneda (COP, USD, MXN)

Se requieren el header x-api-key y Authorization: Bearer <token>.

GEThttps://dev.backend.colurs.co/balance/

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Campo	Tipo	Requerido	Descripción
currency	string	✓	Moneda: COP, USD, MXN
username	string	✕	Solo superusuarios: consultar otro usuario

request.json?currency=COP

curl -X GET "https://dev.backend.colurs.co/balance/?currency=COP" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

response.json

{
"balance": "1500000.00",
"currency": "COP",
"available": "1450000.00",
"pending": 
"50000.00"}

Código	Error	Descripción
400	InvalidCurrency	Moneda no válida o no soportada
403	Forbidden	Sin permisos para consultar
404	ProfileNotFound	Perfil no encontrado

Respuesta:

{
"balance": "1500000.00",
"currency": "COP",
"available": "1450000.00",
"pending": "50000.00"
}

Respuesta:

{
"balance": "500.00",
"currency": "USD",
"available": "480.00",
"pending": "20.00"
}

Respuesta:

{
"balance": "25000.00",
"currency": "MXN",
"available": "24800.00",
"pending": "200.00"
}

Campo	Tipo	Descripción
`balance`	string	Balance total
`currency`	string	Código de moneda
`available`	string	Balance disponible para usar
`pending`	string	Balance pendiente de confirmación

💡

El balance available es lo que realmente puedes usar. El pending incluye transacciones en proceso.

Código	Moneda	Descripción	Endpoint
`COP`	🇨🇴 Peso Colombiano	Moneda principal para Colombia	`GET /balance/?currency=COP`
`USD`	🇺🇸 Dólar	Dólar estadounidense	`GET /balance/?currency=USD`
`MXN`	🇲🇽 Peso Mexicano	México	`GET /balance/?currency=MXN`

Movimientos (Send, Receive, Reload, Convert):

GET /movements/

Equivalencias de wallet:

GET /wallet/equivalent/

Solo header. Devuelve equivalencias entre monedas/saldos.

⚠️

Para usuarios jurídicos: Se valida el estado del onboarding antes de mostrar el balance.

👑

Superusuarios: Pueden consultar el balance de otros usuarios usando ?username=otro_usuario.