Transferencias entre subcuentas

Una transferencia entre subcuentas mueve dinero del saldo de uno de tus usuarios al de otro — un pago entre personas dentro de tu billetera, un movimiento entre la cuenta en COP y la cuenta en USD de un mismo usuario, una corrección entre dos saldos. Las transferencias en la misma moneda son un movimiento de ledger simple. Cuando las dos subcuentas tienen monedas distintas, Core convierte el monto a una tasa de cambio y la transferencia se vuelve una transferencia FX, con dos fees a los que puedes ponerles precio: un cobro fijo por la conversión y tu margen sobre la tasa.

Este flujo hace parte del servicio de ledger de Core. Las transferencias FX deben estar habilitadas para el programa de las cuentas; Mono las habilita al configurar el programa.

Antes de empezar

Vas a necesitar:

• Una API key de Core con el scope ledger.
• Dos subcuentas activas, cuyos propietarios también estén activos, que te pertenezcan.
• Para transferencias FX: la funcionalidad habilitada para el programa de las subcuentas, y — si quieres ponerle precio a la conversión — tus políticas de fees para account_to_account_fx y account_to_account_fx_spread. Mono crea las base; ver Políticas de fees.
• Una clave de idempotencia por transferencia.

Transferencias en la misma moneda

Envía la subcuenta origen, la subcuenta destino y un solo monto — source_amount o target_amount, el otro en null. Ambos son iguales, y la moneda debe ser la de ambas subcuentas. Core registra una transacción de ledger balanceada: un débito en el origen y un crédito en el destino, al instante. No aplican fees.

Transferencias FX

Cuando las subcuentas tienen monedas distintas, el mismo request hace una conversión:

1. Envía source_amount (en la moneda de origen) o target_amount (en la moneda de destino); Core calcula el otro.
2. Opcionalmente envía fx_rate. Si lo omites, Core toma la tasa de mercado vigente — la que publica el endpoint de tasas FX — y le suma tu spread. Si lo envías, Core lo usa tal cual y asume que ya incluye tu spread.
3. Core le pone precio a los dos fees de abajo, registra la transacción y devuelve los montos, la tasa aplicada y calculated_fees.

Los dos fees

Ambos reciben su precio de tus políticas de fees de esos tipos — por programa, propietario de cuenta o cuenta, como cualquier otro fee — y ambos se pueden reemplazar para una sola transferencia a través de override_fees: fixed y tx_description para el fee fijo, percentage para el spread.

Cómo se calculan los montos

fx_rate es la tasa de la moneda destino a la moneda origen — de COP a USD se ve como 4000; de USD a COP, como 0.00025. Con el fee fijo en la moneda de origen:

• Dado el monto destino: source_amount = target_amount × fx_rate + fixed_fee.
• Dado el monto origen: target_amount = (source_amount − fixed_fee) ÷ fx_rate.

Los resultados se redondean a los decimales de cada moneda. Sin un fx_rate explícito, y con un spread del 1% sobre una tasa de mercado de 4000, la tasa aplicada es 4000 × 1.01 = 4040.

Qué devuelve

La respuesta incluye calculated_fees, con una entrada por tipo de fee y el monto final de cada uno en la moneda de origen. El fee de spread es la diferencia entre convertir a la tasa aplicada y convertir a la tasa de mercado — lo que tu usuario pagó por la conversión por encima del precio de mercado. Esos son los montos contra los que conciliar; también aparecen, con su estado y la regla que les puso precio, en el listado de fees.

Pasos

1. Consulta las dos subcuentas y confirma que ambas están activas, y que sus propietarios también lo están.
2. Decide qué monto fijas — lo que paga quien envía o lo que recibe quien recibe — y si pasas tu propio fx_rate.
3. Llama a Realizar una transferencia entre cuentas de ledger con una clave de idempotencia. Un 201 devuelve la transferencia; repetir la misma clave devuelve la misma transferencia con un 200.
4. Lee calculated_fees y los montos de la respuesta y muéstrale a tu usuario qué se cobró.
5. Para volver a encontrar una transferencia por tu propia referencia, usa Buscar una operación de subcuenta exitosa.

Siguientes pasos

• Políticas de fees — define el cobro por conversión y el spread por programa, propietario de cuenta o cuenta.
• Tasas FX — de dónde sale la tasa de mercado.
• Contabilidad de ledger — la contabilidad que produce cada transferencia.