Pedidos, pagos y reembolsos

De una reserva a un pedido pagado

1. El comprador reserva asientos o plazas en el sitio web, luego indica un nombre y un correo, elige un método de pago y acepta las condiciones. No hace falta cuenta.
2. La API convierte la reserva en un pedido (una referencia como TKT-1042) en Awaiting payment, con los importes de la reserva. El navegador nunca envía un precio.
3. El comprador paga en la página propia del proveedor. Los datos de la tarjeta nunca se escriben en tu sitio.
4. El proveedor confirma, y la API emite una entrada por asiento o plaza, marca el pedido como Paid, envía las entradas por correo y avisa al equipo. Cada correo sobre el pedido está en el idioma de la página del sitio web en la que el comprador pagó, inglés o árabe, con el título del evento en ese idioma.

El sitio web nunca decide que un pedido está pagado. Mientras el comprador espera en "Confirming your payment", la API pregunta ella misma al proveedor, así que un pago se convierte en entradas incluso en un portátil al que el webhook del proveedor no llega. Un pago cancelado conserva la reserva para otro intento; uno fallido conserva los datos del comprador.

Métodos de pago

• Cada proveedor se ofrece en cuanto se definen sus claves. Usa primero claves de prueba (sk_test_..., el sandbox de PayPal): no mueven dinero.
• Con PAYMENTS_SIMULATOR=auto, Test payment se ofrece mientras no haya una clave real, así que una instalación nueva puede vender una entrada al instante y una tienda en producción nunca lo muestra.
• En Settings, Payments del panel, cada proveedor aparece como conectado, en modo de prueba o sin configurar, con las variables que definir y su dirección de webhook. Las claves nunca se escriben en el panel.

Webhooks

Antes de salir a producción, registra el webhook en cada proveedor con la dirección pública de tu API:

Cada llamada se comprueba contra la firma del proveedor antes que nada, y cada evento se atiende una sola vez, por muchas veces que llegue. Define STOREFRONT_URL con la dirección del sitio web, adonde las páginas de pago devuelven a los compradores, y PUBLIC_API_URL con la de la API, para el retorno de PayPal.

• Lista de comprobación del despliegue

Entradas gratuitas

Un tipo de entrada con precio 0 no lleva comisión. Cuando un pedido no cuesta nada, el pago no muestra método de pago, el total dice Free, y Get tickets confirma el pedido al instante, con sus pases, su correo y la notificación al equipo, con o sin claves de pago. No se consulta a ningún proveedor, ni siquiera al pago de prueba.

Un pedido gratuito muestra "Free" como su proveedor. No tiene nada que reembolsar: sus entradas se anulan en su lugar. Creative Mornings, de los datos de ejemplo, es un evento gratuito, y Meadow Days vende entradas gratuitas para menores de 12 años.

La comisión de reserva y los impuestos

• La comisión de reserva es un porcentaje del precio de cada entrada, redondeado una vez por entrada y sumado al total del asistente al pagar: siempre la paga el asistente. Se define en Settings, General, de 0 a 20 % (fee_bps, 300 o 3 % en los datos de ejemplo: dos asientos de 20,00 $ suman 41,20 $).
• La moneda es la del espacio de trabajo (USD en los datos de ejemplo), se elige en la misma pestaña entre USD, EUR, GBP, SAR y AED, y se bloquea cuando se paga la primera entrada.
• Ticketory no cobra impuestos. Configura los impuestos de tu país antes de aceptar pagos reales. Las comisiones del proveedor de pagos son aparte.

Estados de los pedidos

La página de pedidos

• Mosaicos para Paid, Pending, Refunded y Failed con sus recuentos, una búsqueda por referencia de pedido, nombre o correo, y filtros por evento, estado del pago (Paid, Free, Pending, Refunded, Failed, In review) y periodo. Lo más nuevo primero, diez por página, con Export CSV.
• La página de un pedido muestra sus detalles, la línea de tiempo del pago con un enlace al panel propio de Stripe o PayPal, sus entradas con Reissue, Void y Refund, y sus reembolsos.

Reembolsos

1. Los reembolsos son de entradas completas. Selecciona las entradas en la página del pedido y pulsa Refund: el importe (el precio de cada entrada y su comisión) lo calcula la API, nunca se escribe. Elige un motivo y marca que el reembolso revoca la admisión.
2. Las entradas se suspenden al instante, así que nadie es admitido con ellas, y el reembolso queda pending hasta que el proveedor lo confirme.
3. Cuando se confirma, las entradas se anulan, sus asientos o plazas vuelven a la venta (salvo que el titular ya hubiera sido admitido), el pedido pasa a reembolsado parcialmente o reembolsado, y el comprador recibe un correo en el idioma del pedido.

Si el proveedor lo rechaza o nunca responde, el reembolso queda failed y las entradas siguen suspendidas hasta que alguien decida: Retry refund lo envía de nuevo con la misma clave del proveedor, así que nunca puede pagar dos veces, y Restore admission devuelve a las entradas su admisión sin mover dinero. Un pedido pagado con el pago de prueba se reembolsa del mismo modo, sin mover dinero; los reembolsos de los pedidos de ejemplo se resuelven unos segundos después de pedirlos.

Un evento cancelado envía un correo a sus compradores pero no mueve dinero: reembolsa cada uno de sus pedidos desde su página.

Quién puede hacer qué

Las rutas que hay detrás

• GET /api/checkout/methods lista lo que se ofrece ahora mismo; POST /api/checkout necesita el X-Hold-Token de la reserva y un Idempotency-Key, y responde la referencia del pedido, la página del proveedor y un token de acceso al pedido, que se envía después como X-Order-Token.
• Una referencia de pedido por sí sola no abre nada: el comprador lee un pedido con ese token o con el token propio del asistente.
• POST /api/admin/orders/:reference/refunds necesita un Idempotency-Key y la version del pedido; una versión más antigua es un 409 VERSION_CONFLICT. Un pedido gratuito responde refund_nothing_left.

• Referencia de la API