El recorrido del dinero

El producto entero es un solo recorrido: se crea una Solicitud de Pago, el pagador la paga, queda como un Pago Recibido, el dinero se acredita en una Billetera y más tarde sale de ella como un Retiro o como un Envío. Cada entrada y cada salida de la Billetera queda escrita como un Movimiento de Saldo.

flowchart LR
  C(["Comercio o integración"]) -->|crea| SP["Solicitud de Pago"]
  SP -->|el pagador la paga| PR["Pago Recibido"]
  PR -->|acredita un Movimiento de Saldo| BI["Billetera"]
  BI -->|debita un Movimiento de Saldo| RE["Retiro a una Cuenta Bancaria propia"]
  BI -->|debita un Movimiento de Saldo| EN["Envío a un Beneficiario"]

Cada parada de ese recorrido tiene después su propia página en «Conceptos». Esta es la que dice en qué orden van y por qué existe cada una.

Una Solicitud de Pago todavía no es dinero

Una Solicitud de Pago lleva un Monto, una Moneda y una descripción, y produce una dirección de checkout: la página donde el pagador elige su medio de pago y paga. Es lo único que se le entrega al pagador, y hasta que alguien la paga no hay dinero de por medio, solo una intención de cobro.

Las creadas por la API se pagan una sola vez y no vencen por sí solas: no llevan fecha de expiración, y ninguna tarea las cierra con el tiempo. Una Solicitud de Pago que ya no debe poder pagarse se cancela; esperar a que caduque es esperar algo que no va a ocurrir.

El comprobante del pagador no significa que el dinero ya esté acreditado

Cuando el pagador paga, la Solicitud de Pago cambia de Estado y se convierte en un Pago Recibido. Pagar y acreditar no siempre ocurren en el mismo instante: en algunos medios de pago —el cobro en USD por transferencia bancaria es el caso típico— el pago queda en curso durante uno a tres días hábiles después de que el pagador ve su comprobante, y la Billetera no recibe nada hasta que ese plazo termina.

De ahí la única regla operativa de esta página: entregar el bien o el servicio contra el Estado de la Solicitud de Pago, nunca contra el comprobante que muestra el pagador. Quien integra tiene la misma regla en su versión técnica: actuar sobre el estado final que trae el webhook, no sobre el regreso del pagador al sitio.

En este paso ocurre además el cambio de moneda, y sobre el resultado se descuenta la Comisión. Por eso el número que se acredita nunca es el número que pagó el pagador.

El dinero vive en una Billetera y cada cambio deja un Movimiento de Saldo

La Billetera es donde queda el dinero cobrado. Cada moneda que la cuenta puede acreditar tiene su Billetera, y una cuenta puede tener varias: la moneda de la Billetera es la que decide en qué se acredita cada cobro.

El Saldo es un número; los Movimientos de Saldo son las filas que lo explican. Ningún cambio de Saldo ocurre sin su Movimiento —ni una acreditación, ni una Comisión, ni una salida—, y eso es lo que hace que el Saldo pueda auditarse hacia atrás en vez de creerse. Mientras una salida está en curso su monto queda reservado: sigue contando en el Saldo, pero ya no está disponible para ordenar otra.

La diferencia entre un Retiro y un Envío es de quién es la cuenta que recibe

Las dos son salidas de dinero desde la misma Billetera y las dos escriben su Movimiento de Saldo. Lo que las separa es el destinatario:

• Un Retiro va a una Cuenta Bancaria del propio comercio, registrada previamente en la cuenta.
• Un Envío va a la cuenta de un tercero, un Beneficiario, también registrado antes de poder recibir nada.

Esa distinción no es formal: decide a quién hay que tener registrado antes de poder ordenar la salida, y cada una tiene además su propio monto mínimo. Lo que no las separa es el costo: las dos descuentan su Comisión al salir, igual que el cobro descontó la suya al entrar.

La API cubre el cobro; la salida se ordena desde el panel

La API tiene dieciséis operaciones: crear, consultar y cancelar Solicitudes de Pago, lo mismo para los cobros con tarjeta, administrar los webhooks, y consultar monedas, medios de pago y conversiones. Ninguna de las dieciséis ordena un Retiro ni un Envío.

Es decir: una integración puede llevar el recorrido entero hasta la Billetera sin intervención humana, y la salida del dinero se ordena desde el panel. Conviene saberlo antes de diseñar la integración, no después. Las dieciséis, llamada por llamada, empiezan en Inicio rápido.

Seguir por aquí

• Qué es Aloha — qué resuelve el producto y para quién.
• Glosario — la definición de cada término que aparece en esta página.
• Solicitudes de Pago — la primera parada, con sus Estados y sus dos montos.
• Saldo y Movimientos — la parada intermedia: qué pasa dentro de la Billetera, y por qué el disponible no es el total.
• Inicio rápido — el mismo recorrido desde la API, en cuatro llamadas copiables.