Billeteras y monedas

Una Billetera guarda dinero de una sola moneda. Eso es casi toda su definición, y de ahí sale la pregunta que importa al integrar: si el pagador paga en una moneda y la cuenta acredita en otra, ¿cuál manda? Esta página responde eso y lo que se deduce de ello.

Lo que pasa dentro de la Billetera una vez que el dinero llegó está en Saldo y Movimientos.

Cada moneda que la cuenta puede acreditar tiene su Billetera, y una cuenta puede tener varias

La primera mitad de esa frase es la que se usa todos los días: para acreditar en una moneda hace falta una Billetera de esa moneda, y no hay forma de acreditar en una moneda que la cuenta no tenga aprovisionada.

La segunda mitad es la que hay que leer despacio, porque el atajo evidente —«una Billetera por moneda»— es falso. Una Billetera no se identifica solo por su moneda, así que una cuenta puede tener dos Billeteras de la misma moneda, cada una asociada a una vía distinta de entrada y salida del dinero. No es un resto de migración ni algo que haya que corregir: una cuenta llega ahí al sumar una segunda vía de cobro sobre una moneda que ya tenía.

Lo que esto cambia para quien integra es menos de lo que parece, y conviene decirlo con precisión: desde la API externa no se elige la Billetera. No hay campo para hacerlo y no hay nada que decidir. Se indica una moneda y Aloha resuelve el resto.

En qué Billetera cae un cobro se deduce de la moneda

Al crear una Solicitud de Pago desde la API externa se manda currency, que es la moneda en la que va a pagar el pagador. Ese campo, junto con lo que la cuenta tenga aprovisionado, es todo lo que interviene; no hay ningún otro dato que la integración pueda mandar para cambiarlo. La regla tiene dos ramas:

• Un cobro en USD se acredita en la Billetera USD. Cobrar en USD exige además que la cuenta tenga esa vía habilitada; si no la tiene, la Solicitud de Pago no llega a crearse y el error lo dice.
• Cualquier otra moneda se acredita en la Billetera local de la cuenta, sea cual sea la moneda de esa Billetera.

La segunda rama es donde vive la conversión. La Billetera local tiene su propia moneda, que no tiene por qué coincidir con la del pagador: un cobro en COP contra una Billetera en CLP es un caso corriente, y ahí el dinero se convierte al entrar. Cuando las dos monedas sí coinciden no hay conversión y no hay nada que decidir —el caso de los cobros en USD, que siempre se acreditan en una Billetera USD—, y eso es lo que hace que amount_type deje de significar algo, como se explica en Solicitudes de Pago.

La moneda en la que va a acreditarse un cobro no se adivina: viaja en la Solicitud de Pago. GET /v1/payment-links/{id} devuelve currency, que es la del pagador, y currency_destiny, que es la de la Billetera que va a recibir el dinero. Cuando las dos son distintas, hay conversión y hay Comisión por cambiar de moneda.

La API del panel funciona de otra manera y merece nombrarse para que nadie la busque en la API externa: al crear una Solicitud de Pago desde el panel, la moneda de la Billetera es un campo obligatorio del formulario. Esa elección existe en pantalla y no existe en la API externa, a propósito.

GET /v1/wallets dice monedas, no Billeteras

Pese al nombre, esa operación no es un inventario de las Billeteras de la cuenta. Es una proyección, y conviene saber qué le falta antes de apoyarse en ella:

• Devuelve monedas, no Saldos. Cada elemento trae únicamente currency. No hay importes, ni identificadores, ni Estados.
• Está deduplicada por moneda. Una cuenta con dos Billeteras de la misma moneda aparece con esa moneda una sola vez. Contar los elementos no cuenta Billeteras.
• Deja fuera las monedas que no son de cobro. Las Billeteras que la plataforma usa por dentro no salen en la respuesta.
• No tiene orden garantizado. La consulta no pide ninguno, así que el orden puede cambiar entre dos llamadas iguales. Leer por posición —«la primera es la principal»— es un error que no falla hoy y falla algún día.

Para lo que sí sirve es para lo que hace falta al integrar: saber en qué monedas puede acreditar esta cuenta. Se lee buscando la moneda, nunca por índice.

En la API

En la API externa, con una Clave API válida y sin ningún Permiso concreto:

Desde la API del panel, bajo /api/v1/clients, hay dos que dan lo que la anterior no da:

La primera es lo más parecido a un inventario que hay: una entrada por cada Billetera en la que la cuenta puede acreditar, con su moneda, su Saldo, su Saldo Reservado y su disponible. La segunda no describe una Billetera sino la Cuenta Bancaria USD —los datos con los que se recibe una transferencia en ella y el saldo que hay en esa cuenta—, y solo responde en las cuentas que la tengan activada.

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.

Relacionado

• Saldo y Movimientos — qué pasa dentro de la Billetera, y por qué el disponible no es el total.
• Comisiones — qué cuesta convertir de una moneda a otra al entrar y al salir.
• Solicitudes de Pago — las dos monedas de un cobro y cuál de los dos montos se fija.
• Pagos Recibidos — los países con cobro local y la moneda del pagador en cada uno.
• Glosario — la definición de cada término de esta página.