Pagos Recibidos

Un Pago Recibido es en lo que se convierte una Solicitud de Pago cobrada. Es el hecho, frente a la promesa que era la Solicitud de Pago, y es lo que explica una acreditación concreta en la Billetera: de dónde vino el dinero, cuánto pagó el pagador, cuánto se descontó y con qué quedó la cuenta.

No nace cuando el pagador termina de pagar, sino cuando el dinero se acredita. En las monedas locales las dos cosas ocurren casi a la vez; en el cobro en USD por transferencia bancaria, entre una y otra hay de uno a tres días hábiles, y durante ese plazo hay un pagador con su comprobante en la mano y todavía ningún Pago Recibido.

Lo que se acredita no es lo que pagó el pagador

Entre las dos cifras pasan dos cosas: el cambio de moneda y la Comisión. Por eso un Pago Recibido guarda las dos puntas y lo que hay en medio: lo que pagó el pagador y en qué moneda —esos dos no salen en la respuesta de la lista ni en la del detalle; se leen en el comprobante en PDF y en la exportación de Pagos Recibidos, que los trae como columnas propias—, el resultado de la conversión, la Comisión que se descontó y el importe que acabó entrando en la Billetera. Este último es el que se acredita, y el que queda escrito en el Movimiento de Saldo correspondiente.

La acreditación y su Movimiento de Saldo se escriben juntos, en una sola operación, contra la Billetera de la moneda en la que se acredita el cobro. Un Pago Recibido sin su Movimiento de Saldo no existe, y es lo que permite reconstruir el Saldo hacia atrás en vez de creerlo.

Casi todos los Pagos Recibidos nacen de una Solicitud de Pago pagada, pero no todos: un depósito recibido en la Cuenta Bancaria USD también produce uno. El campo source los distingue —payment_link o deposit—, los dos aparecen en la lista, y las estadísticas de cobro dejan fuera los depósitos.

Los medios de pago dependen del país

Lo que se le ofrece al pagador en el checkout no es una lista fija: depende del país que elija, y no es la misma en todos. Hoy hay seis países con cobro local:

La lista completa, con los medios de pago de cada país, se consulta en GET /v1/payment-methods. Aloha la pide al proveedor del cobro local y la guarda una hora, así que puede cambiar sin previo aviso, y un país puede venir con la lista vacía si esa consulta falla.

Copiarla dentro de una integración es quedarse con la foto de un día.

USD no está entre esas seis monedas. Un cobro en USD no se hace con un medio de pago local sino con un débito bancario, que el pagador autoriza en el checkout conectando su cuenta bancaria, y que liquida en su propio plazo.

El comprobante del pagador

Cuando el pago se confirma, Aloha genera un comprobante en PDF y se lo manda al pagador por correo, siempre que haya dejado una dirección en el checkout. Sin dirección el comprobante se genera y se guarda igual: lo que no ocurre es el envío.

Puede haber un segundo comprobante, el de la Comisión, y también es condicional: solo se emite cuando la Comisión corrió a cargo del pagador. Eso pasa en dos casos —una Solicitud de Pago creada con la Comisión a cargo del pagador, o un cobro en USD en una cuenta que tenga configurada una Comisión del pagador—, y cuando no se da ninguno de los dos no hay segundo comprobante que esperar.

El cobro en USD por transferencia bancaria mueve esos envíos, y los dos comprobantes se mueven de forma distinta. El del cobro se adelanta: el correo sale cuando el pagador confirma el débito, no cuando el dinero se acredita días después, y el que se emite al acreditar se guarda sin volver a enviarse, porque el pagador ya tiene el suyo. El de la Comisión, en cambio, no se adelanta ni se manda después: cuando lo hay, se genera y se guarda, y al pagador no le llega por correo en ningún momento.

Del lado del comercio, el comprobante de cada Pago Recibido se descarga desde el panel o con GET /api/v1/clients/payins/{id}/receipt, que devuelve una dirección firmada y temporal. Si el comprobante todavía se está generando, la respuesta lo dice y la dirección viene vacía: se vuelve a pedir unos segundos después. El aviso de que un cobro se completó llega además por correo a la cuenta, si las notificaciones de cobro están activadas y hay una dirección configurada para recibirlas.

Un cobro en USD puede devolverse después de haberse acreditado

Esta es la parte que no tiene equivalente en las monedas locales, y conviene leerla entera. Un débito bancario en USD liquida de uno a tres días hábiles después de que el pagador lo autoriza, y el dinero entra en la Billetera al final de ese plazo. Pero el banco del pagador todavía puede revertirlo después: el dinero ya estaba acreditado y se lo llevan de vuelta.

Cuando eso ocurre, la Solicitud de Pago pasa a returned, el Pago Recibido queda marcado como devuelto, y Aloha descuenta el importe de la Billetera con su propio Movimiento de Saldo. Ese descuento no se detiene por falta de Saldo: si el dinero ya se usó, el Saldo disponible puede quedar en negativo hasta que vuelva a entrar dinero.

No se envía ningún aviso cuando pasa. No hay correo, no hay notificación y no hay webhook: entre los seis eventos que la API acepta no hay ninguno para una devolución. Un cobro que se dio por bueno el martes puede dejar de serlo el viernes sin que nada lo anuncie.

La consecuencia es directa y vale la pena escribirla: la conciliación de los cobros en USD corre por cuenta del comercio, y como nada la empuja, hay que ir a mirar. Quedan tres rastros para hacerlo: el Estado de la Solicitud de Pago, que pasa a returned; el Pago Recibido, que queda marcado como devuelto en la lista; y el Movimiento de Saldo del descuento, que deja la fecha y el importe exactos con los que cuadrar la Billetera. Quien entregue bienes o servicios contra un cobro en USD tiene además un motivo para no darlo por cerrado el mismo día en que se acredita.

En la API

Los Pagos Recibidos se consultan desde la API del panel, bajo /api/v1/clients, con el Permiso view_payins:

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 Pagos Recibidos. Quien integra se entera de que un cobro se completó por otras dos vías: consultando la Solicitud de Pago con GET /v1/payment-links/{id} y leyendo su Estado, o suscribiendo un endpoint al evento payment.completed. Las dos están en Webhooks, junto con lo que cada evento trae y lo que no.

Relacionado

• Solicitudes de Pago — de dónde viene un Pago Recibido, y qué se decide al crear la Solicitud.
• El recorrido del dinero — dónde encaja este paso en el resto del producto.
• Webhooks — los seis eventos, cuáles se entregan y cuáles no.
• Checkout embebido — el checkout dentro de la página propia, y los países que sirve.
• Glosario — la definición de cada término de esta página.