Solicitudes de Pago

Una Solicitud de Pago es una orden de cobro: lleva un Monto, una Moneda y una descripción, y produce una dirección de checkout que se le entrega al pagador. Se crea desde el panel o desde la API, y en los dos casos es el mismo objeto, con el mismo recorrido y los mismos Estados. Mientras nadie la pague no hay dinero de por medio: hay una intención de cobro, que puede terminar sin cobrarse.

Es la primera parada de El recorrido del dinero. Esta página la sigue hasta el momento en que alguien la paga; lo que ocurre a partir de ahí está en Pagos Recibidos.

El Monto que se escribe no es siempre el que ve el pagador

Toda Solicitud de Pago tiene dos monedas: la del pagador, en la que paga, y la de la Billetera, en la que se acredita. Por eso tiene también dos montos. Al crearla se fija uno de los dos, con el campo amount_type, y el otro sale de la Tasa de Cambio del momento:

• receive, que es el valor por omisión, fija lo que recibe la Billetera antes de la Comisión. El pagador paga el equivalente, y ese equivalente se calcula cuando el pagador elige cómo pagar, no cuando se creó la Solicitud de Pago.
• charge fija lo que paga el pagador. La Billetera recibe el resultado de la conversión, menos la Comisión.

La elección solo tiene efecto cuando las dos monedas son distintas. Cuando coinciden no hay conversión que anclar, y el campo deja de significar algo. Mandarlo en un cobro en la misma moneda no cambia ni lo que paga el pagador ni lo que se acredita en la Billetera. En la API externa eso incluye a todos los cobros en USD, porque ahí un cobro en USD se acredita siempre en la Billetera USD.

Hay además un mínimo: una Solicitud de Pago por menos del equivalente a 2,00 USD no llega a crearse, y esa comprobación corre antes que la validación del resto del cuerpo.

Quién absorbe la Comisión se decide al crear la Solicitud

Por omisión la Comisión del cobro se descuenta de lo acreditado: la Billetera recibe el Monto menos la Comisión. El campo customer_paid_fee invierte eso —la Comisión se le suma a lo que paga el pagador, y la Billetera recibe entero el Monto declarado—, con tres precisiones que conviene leer antes de apoyarse en él:

• La cuenta tiene que tenerlo habilitado. Una cuenta que no lo tenga y lo mande igual no recibe ningún error: el campo vuelve en silencio a su valor por omisión y la Comisión se descuenta de lo acreditado, como siempre.
• En la API externa el valor por omisión de la cuenta no se aplica. El panel tiene un ajuste que decide cómo nace marcada la casilla de su formulario; la API externa lo ignora a propósito, para que quien integra obtenga el mismo comportamiento con independencia de lo que se toque en el panel. Si el campo no se manda, la Comisión se descuenta.
• La Comisión por cambiar de moneda no entra en este reparto. Esa solo existe cuando las dos monedas son distintas, tiene su propio porcentaje sobre el monto y nunca se le presenta al pagador como una línea aparte. Quién acaba pagándola depende de amount_type, y está en Comisiones.

Los Estados

Tres de los siete —processing, in_transit y returned— los escribe únicamente el camino del cobro en USD por transferencia bancaria, que es el que tarda de uno a tres días hábiles en liquidar. Un cobro en una moneda local no pasa por ninguno de los tres: cuando se paga, va de active a completed en un solo paso.

El Estado es el dato contra el que se decide entregar el bien o el servicio. Un Estado que no se reconozca conviene leerlo como «todavía sin resolver», nunca como un fallo. Y returned merece su propio párrafo, que está en Pagos Recibidos.

Una Solicitud de Pago no caduca sola; la orden del checkout sí

Creada desde el panel o desde la API, una Solicitud de Pago nace sin fecha de caducidad. El barrido que marca caducadas las vencidas se fija en esa fecha, y una Solicitud de Pago que no la tiene no le encaja nunca, así que una Solicitud de Pago que nadie llegó a abrir puede quedarse pagable indefinidamente.

La fecha aparece más tarde y por otro motivo: cuando el pagador entra en el checkout y elige un medio de pago local, se abre una orden de cobro con su propio plazo, y ese plazo queda escrito en la Solicitud de Pago. Si el pagador la abandona y el plazo se agota, la Solicitud de Pago pasa a expired. El cobro en USD por transferencia bancaria no abre ninguna orden con plazo, así que por esta vía no adquiere fecha de caducidad.

De ahí la regla operativa: una Solicitud de Pago que ya no debe poder pagarse se cancela. Esperar a que caduque es esperar algo que, si nadie llegó a abrir el checkout, no va a ocurrir.

Se paga una vez, y se cancela solo antes de pagarse

Toda Solicitud de Pago se crea con un solo uso —max_uses vale siempre 1 y ninguna de las dos API permite cambiarlo—, pero lo que impide de verdad un segundo pago es el Estado: el checkout solo acepta una Solicitud de Pago en active, y en cuanto alguien la paga deja de estarlo.

Cancelar tiene dos condiciones y las dos se comprueban en el momento: la Solicitud de Pago tiene que estar en active y no haber registrado ningún uso. Una ya pagada, ya cancelada, caducada o con un débito en curso no se cancela, y el código del error dice cuál de las dos condiciones falló. Cancelar tampoco es deshacer: lo que corta es la posibilidad de pagarla de ahí en adelante.

En la API

Las operaciones de la API externa, la que se documenta en «Usar la API», son tres:

Cada una exige su propio Permiso en la Clave API —payment_links:create, payment_links:read y payment_links:cancel—, y solo la creación exige además la cuenta verificada. La consulta alcanza todas las Solicitudes de Pago del usuario dueño de la clave, incluidas las creadas desde el panel y las creadas con otras claves de ese mismo usuario; no alcanza las de otro usuario de la misma cuenta. El recorrido completo, con ejemplos, está en Inicio rápido.

El panel llama a su propia API, bajo /api/v1/clients, que no es una superficie de integración y no se documenta aquí: POST /api/v1/clients/payment-links para crear, GET /api/v1/clients/payment-links y GET /api/v1/clients/payment-links/{id} para listar y consultar, y PATCH /api/v1/clients/payment-links/{id}/cancel para cancelar. Se nombran para poder emparejar lo que se ve en pantalla con la operación que hay detrás: crear exige las mismas verificaciones y el mismo mínimo que en la API externa, y cancelar comprueba las mismas dos condiciones.

Relacionado

• Pagos Recibidos — en qué se convierte una Solicitud de Pago cuando alguien la paga.
• El recorrido del dinero — dónde encaja este paso en el resto del producto.
• Inicio rápido — crear y consultar una Solicitud de Pago desde la API, paso a paso.
• Checkout embebido — cobrar sin sacar al pagador de la página propia.
• Glosario — la definición de cada término de esta página.