# Saldo

Consulta tu saldo de Polar (disponible, retenido y retirado) y su estimado en tu moneda local.

> [!WARNING]
> El SDK `vexor` de npm (Stripe, MercadoPago, PayPal, Square, Talo) está **deprecado**: ya no se mantiene y no debe usarse. vexorpay es hoy una **API REST de links de pago en USD sobre Polar (Merchant of Record), sin SDK oficial**. Migración: <https://developers.vexorpay.com/docs/migracion-desde-el-sdk>

Fuente: <https://developers.whop.vexorpay.com/docs/api/balance>

`GET /api/v1/balance`

Devuelve en `polar` tu **saldo de Polar**, donde Polar acredita tus ventas:

| Campo | Qué es |
| --- | --- |
| `availableCents` | Disponible para retirar. |
| `pendingCents` | Retenido por Polar: cada cobro queda retenido 7 días. `nextReleaseAt` / `nextReleaseCents` dicen cuándo y cuánto se libera. |
| `paidOutCents` | Lo que ya retiraste (o está en camino). |
| `balanceCents` | Disponible + retenido. |
| `payoutAccountReady` | `false` si todavía no configuraste en Polar la cuenta donde recibís los retiros. |
| `financeUrl` | Página de finanzas de tu organización en Polar. También puedes retirar por API con [`POST /api/v1/payouts`](/docs/api/payouts). |
| `localEstimate` | El mismo saldo en la moneda local de tu cuenta de cobro (ver abajo). |

### `localEstimate`: el saldo en tu moneda

Cuando retirás desde Polar, **Stripe** convierte los dólares a la moneda de tu cuenta de cobro. `localEstimate` usa **esa misma cotización de Stripe** (no la de otro proveedor), así el estimado coincide con lo que recibís:

| Campo | Qué es |
| --- | --- |
| `currency` | Moneda local, en minúsculas (`ars`, `clp`, `cop`, `pen`, `uyu`…). |
| `currencySource` | `payout_account` (moneda de tu cuenta de cobro de Polar) o `country` (todavía sin cuenta de cobro: moneda de tu país). |
| `rate` | Unidades de moneda local por 1 USD, con el fee de conversión de Stripe incluido (`fxFeeRate`, hoy 1 %). |
| `asOf` | Hora de la cotización (se renueva cada 15 minutos). |
| `available` | Estimado de lo que llega al retirar el disponible. Con `availableBasis: "payout_estimate"` ya descuenta las comisiones de retiro de Polar; con `"gross"`, está calculado sobre el bruto. |
| `pending` | Estimado del saldo retenido. |
| `paidOut` | Lo ya retirado, con el **monto exacto** que acreditó Stripe en cada retiro (`paidOutExact: false` si algún retiro fue en otra moneda). |

Los montos van en la unidad menor de la moneda (centavos; en monedas sin decimales, como `clp`, unidades). `available` y `pending` son estimados: el monto final se fija con la cotización del momento del retiro. `localEstimate` es `null` si tu cuenta de cobro está en USD o si no hay cotización disponible.

Si no conectaste Polar, `polar` es `{ "connected": false }`. Si tu conexión es anterior a este permiso, `polar.needsReconnect` es `true`: reconecta Polar desde el dashboard. Si Polar no responde, `polar.unavailable` es `true` y el resto de la respuesta llega igual.

El entorno lo define la API key: con una clave de prueba (`vxp_test_...`) lees el saldo de Polar de prueba. La respuesta trae además `connected` (igual a `polar.connected`), `sandbox` y `updatedAt`.

**curl**

```bash
curl https://api.vexorpay.com/api/v1/balance \
  -H "Authorization: Bearer vxp_live_tu_clave"
```

**Node.js**

```js
const res = await fetch('https://api.vexorpay.com/api/v1/balance', {
  headers: { Authorization: 'Bearer vxp_live_tu_clave' },
})

const data = await res.json()
```

**PHP**

```php
<?php

$client = curl_init('https://api.vexorpay.com/api/v1/balance');
curl_setopt_array($client, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer vxp_live_tu_clave'],
]);

$data = json_decode(curl_exec($client), true);
```

**Python**

```python

response = requests.get(
    'https://api.vexorpay.com/api/v1/balance',
    headers={'Authorization': 'Bearer vxp_live_tu_clave'},
)
data = response.json()
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.vexorpay.com/api/v1/balance", nil)
req.Header.Set("Authorization", "Bearer vxp_live_tu_clave")

res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
```

### Respuesta exitosa

`200 OK`

```json
{
  "polar": {
    "connected": true,
    "needsReconnect": false,
    "currency": "usd",
    "balanceCents": 4713,
    "availableCents": 0,
    "pendingCents": 4713,
    "nextReleaseAt": "2026-10-31T07:55:38.123Z",
    "nextReleaseCents": 4713,
    "paidOutCents": 0,
    "payoutAccountReady": false,
    "financeUrl": "https://polar.sh/dashboard/mi-org/finance",
    "localEstimate": {
      "currency": "ars",
      "currencySource": "payout_account",
      "rate": 1514.26,
      "fxFeeRate": 0.01,
      "asOf": "2026-10-25T12:00:00.000Z",
      "source": "stripe_fx_quote",
      "available": 0,
      "availableBasis": "gross",
      "pending": 7136707,
      "paidOut": 0,
      "paidOutExact": true
    }
  },
  "connected": true,
  "sandbox": false,
  "updatedAt": "2026-01-02T12:06:00.000Z"
}
```

Sin Polar conectado devuelve `200` con `{ "connected": false, "polar": { "connected": false }, "sandbox": false, "updatedAt": "..." }`.

## Errores

| Error | HTTP | Causa |
| --- | --- | --- |
| `unexpected_error` | 500 | No pudimos leer el saldo de tu cuenta. |