Balance

Endpoint to query account balance.

GET /v1/balance

Returns the authenticated user's balance, including total balance, available for withdrawal and held.

Headers

Authorization: Bearer {access_token}

Request Example

curl -X GET https://api.misespay.com/v1/balance \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

{
  "success": true,
  "data": {
    "total": {
      "cents": 150000,
      "amount": 1500.0,
      "formatted": "R$ 1.500,00"
    },
    "available": {
      "cents": 100000,
      "amount": 1000.0,
      "formatted": "R$ 1.000,00"
    },
    "hold": {
      "cents": 50000,
      "amount": 500.0,
      "formatted": "R$ 500,00"
    }
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the operation was successful
data.total	object	Total account balance
data.total.cents	integer	Total amount in cents
data.total.amount	number	Total amount in reais
data.total.formatted	string	Total amount formatted (e.g. "R$ 1.500,00")
data.available	object	Balance available for withdrawal
data.available.cents	integer	Available amount in cents
data.available.amount	number	Available amount in reais
data.available.formatted	string	Available amount formatted
data.hold	object	Held/blocked balance
data.hold.cents	integer	Held amount in cents
data.hold.amount	number	Held amount in reais
data.hold.formatted	string	Held amount formatted

Balance Types

Total

Sum of all money in the account (available + held).

Available

Amount that can be withdrawn immediately. This is the balance used to validate withdrawals.

Hold

Amount temporarily blocked by:

• Sales in processing
• Withdrawals pending approval
• Compliance reviews
• Disputes or chargebacks

Possible Errors

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

500 Internal Server Error

{
  "success": false,
  "message": "Error querying balance"
}

Value Formats

The API returns values in three formats to facilitate different use cases:

Cents

• Type: Integer
• Use: Precise calculations, avoids floating point issues
• Example: 150000 = R$ 1,500.00

Amount (Reais)

• Type: Number (float)
• Use: Display and simple calculations
• Example: 1500.00

Formatted

• Type: String
• Use: Direct display to users
• Example: "R$ 1.500,00"

TIP

For precise calculations, always use the value in cents to avoid rounding issues with decimal numbers.

Recommended Flow

1. Query balance before creating withdrawals
2. Check available (not total) to validate if there's sufficient balance
3. Consider withdrawal fee (R$ 0.20) in the calculation
4. Update balance after sale or withdrawal operations

Next Steps

• Withdrawals - Create withdrawals
• Sales - Create sales and receive payments