Conversiones USD

Una conversión pasa saldo de la Cuenta Bancaria USD a la Billetera local del comercio. Se indica un monto en dólares, se descuenta de la cuenta en dólares y se acredita el equivalente en la moneda de la Billetera.

Es la vía por la que el dinero cobrado en dólares llega a donde sirve para lo demás. Con el saldo de la Cuenta Bancaria USD no se ordena un Retiro ni un Envío; una vez convertido, sí.

Va en una sola dirección. No existe la operación inversa: no se pasa saldo de la Billetera local a la cuenta en dólares.

Y conviene despejar un cruce de nombres antes de seguir, porque la palabra está usada dos veces en estas páginas. POST /v1/conversions/quote y POST /v1/conversions/rate, en la API externa, no mueven dinero: cotizan un cambio de moneda para decidir un precio, y están en Comisiones. Lo de esta página mueve dinero de verdad y no está en la API externa.

No se elige la Billetera de destino

Se manda un monto y nada más. La Billetera que recibe es la local principal de la cuenta, y el propio cálculo previo dice en qué moneda va a acreditar antes de comprometer nada: lo devuelve en currency. Una cuenta que acredita en más de una moneda no elige aquí, igual que no elige al crear una Solicitud de Pago.

Tampoco hay mínimo. La validación pide un monto mayor que cero y con como mucho ocho decimales, y su techo es tan alto que no es un límite de negocio sino una guarda técnica. El piso real es el saldo disponible en la cuenta en dólares: pedir más de eso se rechaza por saldo insuficiente, con lo pedido y lo disponible en el error.

Se cotiza antes de comprometerla

Hay una operación de cálculo previo, aparte de la que ejecuta. Devuelve, para el monto que se le pase:

No reserva nada, no crea nada y no deja rastro. Es un cálculo.

La Comisión ya está descontada, y por eso el cálculo dice cero

Esta es la parte que hay que leer entera, porque fee_amount en cero y fee_label en Free se prestan a la lectura equivocada. No significan que la operación no tenga coste. Significan que no hay ninguna Comisión que se cobre aparte: la Comisión por cambiar de moneda ya se descontó del monto antes de la conversión, y la tasa que se devuelve viene con eso dentro.

El orden es el mismo que en cualquier salida: la Comisión se descuenta del monto antes de aplicar la conversión, y lo que se convierte es el resto. La exchange_rate del cálculo no es la tasa de referencia del mercado, sino la tasa ya cargada con eso, que es exactamente lo que hace que you_receive sea el número honesto y que el desglose no se pueda reconstruir desde ahí. Es el número correcto para decidir, y el número equivocado para auditar una Comisión.

Hay un caso en el que esa Comisión es cero por construcción: cuando la Billetera de destino también es en dólares no hay cambio de moneda, así que no hay nada que cobrar por él. Fuera de ese caso el porcentaje se configura por cuenta, como el resto de las Comisiones, y puede ser distinto en dos cuentas distintas.

Una tasa cotizada es una cotización, no una promesa

El cálculo previo no fija la tasa. No devuelve ningún identificador de cotización, no devuelve ninguna fecha de caducidad, y la operación que ejecuta la conversión no admite ninguna de las dos cosas: solo acepta un monto. No hay nada que reservar ni nada que presentar después.

La tasa que se aplica de verdad es la que se calcula en el momento de liquidar, con los precios vigentes entonces. Aloha guarda los precios un rato para no pedirlos en cada consulta, y al liquidar los vuelve a pedir si los que tenía ya vencieron. Entre el cálculo previo y la liquidación pasa tiempo, así que una diferencia pequeña entre lo cotizado y lo acreditado es lo esperable, no un fallo.

La conclusión práctica es corta: el cálculo previo sirve para decidir, y lo acreditado se lee del resultado. Mostrarle a alguien el número del cálculo previo como si fuera el importe final es prometer algo que no se controla.

Una a la vez, y mientras tanto el dinero está reservado

No puede haber dos conversiones en curso a la vez. Pedir una segunda mientras la primera no ha terminado se rechaza con un 409, sin crear nada. Es la misma restricción que impide comprometer dos veces el mismo saldo.

Al crear la conversión, su monto sale del saldo disponible de la cuenta en dólares y pasa a estar reservado. Como toda reserva, no deja fila en la lista de Movimientos de Saldo: el disponible baja y todavía no hay nada que apuntar. La fila aparece al final, cuando el dinero se mueve de verdad.

Termina de una de dos maneras:

• Completada. Se descuenta el monto de la cuenta en dólares y se acredita el resultado en la Billetera local.
• Fallida. La reserva se suelta y el monto vuelve al disponible. No hubo movimiento de dinero, así que tampoco hay nada que apuntar.

No hay ninguna operación para cancelar una conversión. Una vez pedida, termina por sí misma.

Y hay un caso en el que no termina, que conviene conocer aunque sea raro, porque no se resuelve solo: una conversión puede quedarse a medio camino, sin completarse y sin fallar, con el monto todavía reservado. No hay hoy ningún proceso que la destrabe automáticamente. Se reconoce porque el disponible no vuelve y la conversión no llega a un estado final, y se resuelve con soporte.

Lo que deja escrito, en los dos lados

Una conversión completada se ve en dos sitios distintos y con dos nombres que no se parecen a «conversión», lo cual es motivo suficiente para decirlo aquí:

• En la cuenta en dólares deja un Movimiento de Saldo de salida cuya etiqueta es Payout —la misma que la de un Retiro—. La lista de Movimientos describe el resultado, no el mecanismo, y para el Saldo esto es dinero que sale.
• En la Billetera local deja una entrada que se registra como un Pago Recibido con source en deposit, por el importe acreditado y sin Comisión propia. Aparece en la lista de Pagos Recibidos, y las estadísticas de cobro lo dejan fuera por ser un depósito.

Cuadrar una conversión es, entonces, emparejar esas dos filas: lo que salió en dólares y lo que entró en la moneda local.

En la API

Las conversiones se piden y se consultan desde la API del panel, bajo /api/v1/clients:

Las cuatro exigen además tener la Cuenta Bancaria USD habilitada en la cuenta, y sin eso se rechazan con 403 FEATURE_NOT_ENABLED.

Tanto el cálculo previo como la petición reciben un único campo, amount, en dólares. El listado acepta filtrar por status, y ahí solo hay tres valores: processing, completed y failed. processing agrupa todo lo que no ha terminado.

Ese agrupamiento es de la consulta, no del dato: el status de una conversión concreta puede traer un valor intermedio más fino que ninguno de esos tres. La forma segura de leerlo es comprobar completed y failed, y tratar todo lo demás como «en curso».

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 convierte saldo: cubre el cobro y termina en la Billetera.

Relacionado

• Cuenta bancaria USD — de dónde sale el saldo que se convierte, y qué hace falta para tenerla.
• Comisiones — la Comisión por cambiar de moneda, y por qué no aparece como una línea aparte.
• Saldo y Movimientos — la reserva, y por qué el disponible baja sin dejar fila.
• Billeteras y monedas — cuál es la Billetera que recibe y por qué no se elige.
• Pagos Recibidos — la entrada que deja una conversión, y el campo que la distingue de un cobro.
• Glosario — la definición de cada término de esta página.