Saldo y Movimientos

La Billetera es donde queda el dinero entre que entra y sale. El Saldo es cuánto hay; los Movimientos de Saldo son las filas que explican cómo llegó a ser ese número. Esta página es sobre las dos cosas y sobre la distancia que hay entre ellas.

Es la parada intermedia de El recorrido del dinero: lo que entra viene de un Pago Recibido, y lo que sale se ordena desde el panel como un Retiro o un Envío.

Hay dos Saldos, y el que se puede usar es el menor

Una Billetera no lleva un número, lleva varios, y para leer el resto de esta página hacen falta estos:

• El Saldo es todo el dinero que hay en la Billetera.
• El Saldo Reservado es la parte que ya está comprometida con una salida en curso.
• El Saldo disponible es lo que queda: lo único que se puede comprometer en una salida nueva.

La relación entre los tres no es una convención de presentación: es una condición que el movimiento de dinero comprueba, y que hace fallar la operación entera —sin escribir nada— cuando no se cumple. Dice esto: el Saldo es la suma del disponible y el reservado, y el reservado no baja de cero. De ahí se sigue la regla que sorprende: el Saldo disponible nunca es mayor que el Saldo, y es estrictamente menor siempre que haya algo reservado.

La consecuencia práctica llega en el peor momento, que es cuando se quiere sacar dinero. Al ordenar un Retiro o un Envío, su monto se reserva en el acto: sale del disponible y se queda dentro del Saldo. Durante todo el tiempo que la salida esté en curso —que no es instantáneo— ese dinero ya no se puede usar para ordenar otra, aunque el Saldo lo siga contando y aunque todavía no haya salido de ninguna cuenta. Un Saldo de mil con una salida de novecientos en curso no permite ordenar una salida de doscientos.

Cuando la salida termina, la reserva se resuelve de una de dos maneras, y las dos son limpias:

• Si se completa, el monto deja de estar reservado y se descuenta del Saldo. El disponible no se mueve: ya se había movido al reservar.
• Si falla o la rechazan, el monto deja de estar reservado y vuelve al disponible. El Saldo nunca se movió.

Lo que se comprueba al ordenar una salida es el menor de los dos números, no el Saldo. Pedir más que eso devuelve un error de Saldo insuficiente y no llega a crear nada.

Una reserva no deja Movimiento, y eso es correcto

Reservar mueve el disponible y el reservado en direcciones opuestas por el mismo importe. El Saldo, por tanto, no cambia. Y como un Movimiento de Saldo es exactamente el registro de un cambio de Saldo, reservar no escribe ninguno: no hay nada que registrar.

Esto se nota al mirar una Billetera cuyo disponible bajó sin que aparezca una fila nueva en la lista. No falta un Movimiento: es que todavía no ocurrió nada que merezca uno. El dinero sigue ahí, comprometido con una salida que aún no terminó. Lo que explica ese hueco no está en la lista de Movimientos sino en el Estado de la salida que lo causó, que se consulta en el panel.

Cuando esa salida se complete, el Movimiento aparecerá, y llevará el importe completo.

Qué lleva un Movimiento, y hasta dónde llega la lista

Cada Movimiento dice qué lo causó, cuánto movió, en qué moneda, con qué Saldo quedó la Billetera inmediatamente después y cuándo fue. Ese penúltimo dato es útil para leer una fila sin tener que reconstruirla: dice en qué punto dejó a la Billetera ese movimiento concreto, en el instante en que se escribió.

Lo que hace legible a esa lista es la forma en que se corrige. Deshacer una operación no reescribe, por norma, la fila que la registró: escribe otra que la compensa. Un cobro que se revierte, una Comisión que se devuelve o un ajuste manual entran así, como filas nuevas con su propia fecha, y la original se queda donde estaba. Por eso la historia de una Billetera se lee hacia atrás como una suma de hechos, y no como un número que alguien fue corrigiendo encima.

La excepción es el mantenimiento. El equipo de Aloha puede corregir un cobro concreto que se cobró con una Comisión equivocada reescribiendo su fila y ajustando el Saldo, en lugar de añadir una fila nueva. No es el camino normal, y nada de lo que haga el comercio lo dispara; lo que implica es que una fila ya leída no es un dato congelado, y que para cuadrar manda el Saldo de la Billetera por encima de la copia que se guardara de la lista.

Dos precisiones para quien lea la respuesta de la API en lugar del panel:

• La dirección se lee en direction, no en el signo de amount. El campo direction vale in o out y es el dato bueno. El signo de amount no lo acompaña siempre: una salida completada llega con el importe en negativo, pero un cobro que se devolvió después de acreditarse —que también resta— llega con el importe en positivo. Decidir la dirección por el signo se equivoca justo en el caso raro.
• label es un texto corto en inglés. Describe el resultado —Payment received, Payout, Payment returned, Deposit, Refund o Adjustment, y Movement si llega un tipo que la respuesta no sabe nombrar— y está pensado para mostrarse, no para ramificar el código. Para eso está direction.

La lista que devuelve la API es la del comercio: enseña el dinero que entra y el que sale, y deja fuera las filas de contabilidad interna de la plataforma. No es una vista recortada por comodidad, es lo que se busca casi siempre. Pero tiene una consecuencia que conviene tener presente antes de cuadrar nada: la lista, por sí sola, no siempre explica el Saldo. Ni sumar sus importes ni leer el Saldo que dejó su fila más reciente tiene por qué dar el Saldo de hoy, porque entre esa fila y hoy puede haber movimientos que la lista no enseña: es exactamente lo que ocurre con la Comisión de un cobro en USD, que se descuenta después de acreditarlo y no aparece. El Saldo que manda es el de la Billetera, y se consulta directamente con GET /api/v1/clients/virtual-wallets, en Billeteras y monedas.

El Saldo disponible puede quedar en negativo

No hay nada que lo impida, y es deliberado. La condición de más arriba protege al reservado de irse por debajo de cero y obliga a que las tres cifras cuadren entre sí; no exige que el disponible sea positivo.

El caso real está en Pagos Recibidos: un cobro en USD puede devolverse días después de haberse acreditado, y el descuento se aplica igual aunque el dinero ya se haya usado. El Saldo disponible queda en negativo hasta que vuelva a entrar dinero, y el Movimiento del descuento queda escrito como cualquier otro. Nada avisa de que ocurrió.

En la API

Los Movimientos se consultan desde la API del panel, bajo /api/v1/clients, con el Permiso view_balance_movements:

Las dos son de una Billetera, no de la cuenta entera: el parámetro virtual_wallet_id dice de cuál. Conviene mandarlo siempre. Si se omite, la respuesta sale igualmente, pero de una de las Billeteras de la cuenta elegida sin un criterio definido, lo que en una cuenta con más de una Billetera es una respuesta correcta sobre la Billetera equivocada.

La lista acepta además type para filtrar por familia de movimiento, start_date y end_date para acotar por fecha, y per_page hasta cincuenta; llega ordenada de más reciente a más antigua y paginada. Los totales, en cambio, son de toda la vida de la Billetera: no aceptan fechas.

Esa API es la que usa el panel; no es una superficie de integración y no se documenta aquí. Se nombra para poder emparejar lo que se ve en pantalla con la operación que hay detrás. La API externa no tiene operaciones de Saldo ni de Movimientos.

Relacionado

• Billeteras y monedas — cuántas Billeteras tiene una cuenta y cuál recibe cada cobro.
• Comisiones — por qué lo que se acredita es menor que lo que se cobró, y por qué la Comisión no aparece como su propio Movimiento.
• Pagos Recibidos — de dónde viene cada acreditación, y el cobro que se devuelve después de acreditarse.
• El recorrido del dinero — dónde encaja esta parada en el resto del producto.
• Glosario — la definición de cada término de esta página.