Balance
Endpoint to query user balance.
Balance is queried by specific currency. You must indicate which currency you want to check.
Get Balance
Gets the user’s available balance in a specific currency.
Endpoint
GET /balance/Headers
Authorization: Bearer [ACCESS_TOKEN]
Accept: application/json
x-api-key: [API_KEY]Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
currency | string | ✅ | Currency: COP, USD, USDT |
username | string | ❌ | Superusers only: query another user |
Examples by Currency
Colombian Peso
curl -X GET "https://dev.backend.colurs.co/balance/?currency=COP" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"Response:
response.json
{
"balance": "1500000.00",
"currency": "COP",
"available": "1450000.00",
"pending": "50000.00"
}Response Fields
| Field | Type | Description |
|---|---|---|
balance | string | Total balance |
currency | string | Currency code |
available | string | Available balance to use |
pending | string | Pending confirmation balance |
💡
Note: The available balance is what you can actually use. pending includes transactions in process.
Supported Currencies
| Code | Currency | Description |
|---|---|---|
COP | 🇨🇴 Colombian Peso | Main currency for Colombia |
USD | 🇺🇸 Dollar | US Dollar |
USDT | 💎 Tether | Stablecoin pegged to USD |
Possible Errors
| Code | Error | Description |
|---|---|---|
400 | InvalidCurrency | Invalid or unsupported currency |
403 | Forbidden | No permission to query |
404 | ProfileNotFound | Profile not found |
Important Notes
⚠️
For juridical users: Onboarding status is validated before showing balance.
👑
Superusers: Can query other users’ balance using ?username=other_user.
Example for Superusers
curl -X GET "https://dev.backend.colurs.co/balance/?currency=COP&username=other_user" \
-H "Authorization: Bearer [SUPER_ADMIN_TOKEN]" \
-H "x-api-key: [API_KEY]"