Conectar Payora a un sitio PHP personalizado

Cómo conectar Payora a un sitio web PHP personalizado

Si tu sitio está construido en PHP de forma independiente, el proceso es directo: crea el pago, envía al cliente a Payora y luego devuelve el resultado a tu propio sistema de pedidos. No hace falta WooCommerce. Tampoco un laberinto de plugins.

Esta guía se centra en cómo integrar Payora en PHP y en cómo conectar Payora a sitio web PHP personalizado sin convertir tu proceso de pago en un proyecto de ciencia ficción. Verás los puntos exactos en los que PHP debe iniciar el pago, dónde debe recibir el retorno y dónde tu app debe decidir si el pedido está pagado, pendiente o fallido.

1. Confirma el patrón de integración para un sitio PHP personalizado

Empieza con una decisión: ¿vas a crear un enlace de pago sencillo, una solicitud de pago del lado del servidor o un flujo de pago completo con seguimiento de pedidos? No son lo mismo. Un sitio de donaciones de una sola página puede funcionar con un enlace de pago, mientras que una tienda con 20 productos normalmente necesita crear el pedido en el servidor antes de que el cliente salga de tu sitio.

Para un sitio web PHP personalizado, el patrón más limpio suele ser: crear el pedido localmente, generar el pago de Payora desde PHP, redirigir al cliente y después escuchar el retorno y la confirmación del servidor. Así tienes un registro en tu lado antes de que se mueva el dinero. También mantiene la lógica del carrito y la factura dentro de tu app, donde corresponde.

Si tu proceso de pago es pequeño, quizá solo necesites una redirección a una página de pago alojada por Payora. Si necesitas líneas de pedido, notas del cliente o ID de pedido, tu código PHP debe enviar esos datos antes de la redirección. Sencillo. No simplista.

Un ejemplo práctico ayuda. Una agencia digital que vende un paquete de mantenimiento en 3 pasos puede crear el pedido en PHP, adjuntar el correo del cliente y enviar al cliente a Payora con la referencia de la factura. Un proyecto personal que vende una sola clave de licencia puede necesitar solo el enlace de pago y una página de retorno. La diferencia está en la cantidad de estado que necesitas conservar, no en la cantidad de código.

2. Mapea las páginas, endpoints y flujo de sesión exactos

Antes de escribir código, enumera las páginas. Necesitas al menos tres: una página de pago, una página de retorno y un endpoint del servidor para la confirmación del pago. Si omites este mapeo, acabarás adivinando qué solicitud cambió el pedido. Y adivinar sale caro.

Usa una sesión PHP normal para el flujo del navegador, pero no confíes solo en la sesión. El estado de la sesión puede desaparecer si el cliente cambia de dispositivo, cierra la pestaña o vuelve de Payora más tarde. Guarda también el ID del pedido en tu base de datos, para que tu código PHP pueda encontrar la transacción aunque la sesión del navegador ya no exista.

Un flujo típico se ve así:

• La página de pago recopila producto, correo electrónico y cantidad.
• PHP crea un pedido local con estado pendiente.
• PHP envía al cliente a Payora.
• Payora devuelve el navegador a tu URL de retorno.
• Tu servidor comprueba el estado del pago antes de marcar el pedido como pagado.

Ese flujo mantiene separados la página de retorno del navegador y la verdad del lado del servidor. Bien. Deben estar separadas. El navegador puede decirte lo que vio el cliente; tu servidor debe decidir qué significa el pedido.

Un hábito pequeño te ahorra horas más adelante: guarda la referencia de pago de Payora junto con tu ID de pedido en cuanto crees el pago. Si esperas hasta después de la redirección, un error de red o un refresco impaciente puede dejarte con un pedido y sin referencia de Payora. Entonces te tocará hacer de detective en producción.

3. Prepara una capa mínima de solicitudes de pago en PHP

Mantén el código de pagos fuera de las plantillas. Un pequeño helper o clase PHP basta. Un método puede construir la carga útil, otro puede enviar la solicitud HTTP y un tercero puede analizar la respuesta. Esa separación importa porque la lógica de pago cambia más a menudo que el marcado de una página.

Por ejemplo, tu helper puede recibir un array con amount, currency, order_id y return_url, y luego añadir tus credenciales de Payora desde variables de entorno. La página de pago nunca debería saber dónde vive el token de API. Solo debería saber qué botón se pulsó.

Aquí tienes la forma de la lógica, no una implementación completa:

1. Lee el pedido desde tu base de datos.
2. Construye un array de solicitud para Payora.
3. Envía la solicitud con cURL o un cliente HTTP similar.
4. Guarda la referencia de pago devuelta por Payora.
5. Redirige al cliente a la URL de pago de Payora.

Mantén ese helper simple. El código simple es más fácil de probar. El código simple falla menos cuando cambias el precio de un producto o añades un segundo formulario de pago el mes que viene.

Si ya tienes una abstracción de pagos en tu app, úsala. Si no, crea un archivo y ponle un nombre claro, como PayoraClient.php. Ese archivo debe contener las credenciales, las llamadas a la API y el análisis de respuestas. Nada más. Ni HTML. Ni CSS. Ni un mensaje de agradecimiento.

4. Envía al cliente a Payora desde tu proceso de pago personalizado

Una vez que exista el pedido local, envía la solicitud de pago a Payora y manda al cliente a la página de pago de Payora. El traspaso debe ocurrir solo después de que tu servidor haya guardado el pedido, porque el usuario puede cerrar la pestaña en cuanto empiece la redirección.

Pasa los datos del pedido que realmente necesitas. Normalmente eso significa ID de pedido, importe, moneda y correo del cliente. También puedes enviar metadatos como el nombre del producto o el ID interno de la cuenta, pero no vuelques todos los campos de tu base de datos en la solicitud solo porque están disponibles. Los datos extra pueden generar confusión más adelante cuando soporte compare registros.

Un proceso de pago personalizado suele usar un formulario POST con un botón “Pagar ahora”. Ese formulario se envía a tu endpoint PHP, el endpoint crea el pago en Payora y luego responde con una redirección. El cliente nunca ve la respuesta de la API. Solo ve Payora.

Una pequeña advertencia: no confíes en totales calculados en el cliente. Si tu página de producto dice 49 $ y el navegador envía 39 $, tu servidor debe rechazar la discrepancia. Una solicitud de pago debe crearse a partir del total del pedido del lado del servidor, no del valor oculto en el formulario. Esa regla importa siempre.

Si quieres una visión más amplia de los patrones de configuración de pagos, la guía sobre la pasarela de pagos cripto para ecommerce ofrece contexto útil sin repetir aquí el flujo PHP.

5. Recibe y valida el resultado del pago en tu propia app

La URL de retorno del navegador es útil, pero no es la última palabra. Puede indicar que se visitó la página de pago y puede llevar un valor de estado, pero tu app PHP debe seguir tratando ese resultado como provisional hasta que el servidor lo confirme. Pendiente no es pagado.

Diseña la página de retorno para manejar tres casos: éxito, pendiente y fallo. Si Payora indica éxito, muestra una página de agradecimiento y dile al usuario que el pedido se está confirmando. Si el estado es pendiente, di exactamente eso. Si falló, invita al cliente a intentarlo de nuevo sin perder el registro del pedido. Un texto claro reduce los tickets de soporte.

Hay una regla útil aquí: la página de retorno nunca debe crear por sí sola el pedido pagado. Solo debe mostrar el estado actual y, quizá, ofrecer un enlace de vuelta a la página del pedido. La actualización de la base de datos ocurre después de la verificación, no después de una redirección del navegador. Esa diferencia te protege de actualizaciones dobles accidentales.

Mantén el endpoint de retorno lo bastante simple como para leerlo de un vistazo. Si recibe una referencia de pago de Payora, búscala. Si falta la referencia, registra la solicitud y detente. Si el pedido ya está pagado, muestra un mensaje amable y evita cambiar nada. Así es como los flujos idempotentes se mantienen tranquilos ante refrescos repetidos.

Para equipos que también quieren una comparación del lado del proceso de compra, el artículo sobre cómo aceptar pagos cripto tiene notas útiles de facturación, especialmente si vendes servicios con facturas recurrentes o aprobaciones manuales.

6. Confirma la transacción en el servidor antes de marcar el pedido como pagado

Este es el paso más seguro. Tu app PHP debe consultar Payora del lado del servidor y confirmar el estado de la transacción antes de marcar el pedido como pagado. Las redirecciones del navegador pueden mentir por omisión; las comprobaciones del servidor no se preocupan por si el cliente cerró la pestaña, la refrescó dos veces o usó un segundo dispositivo.

Usa la referencia de pago de Payora guardada antes y solicita el estado actual de la transacción. Compara el estado devuelto con el estado que necesitas para completar el pedido. Si la transacción está liquidada o confirmada, actualiza el pedido. Si está pendiente, mantén el pedido pendiente. Si falló o se canceló, no toques el pedido.

Un apunte: aquí es donde muchos sitios PHP personalizados se descuidan. Confían en la página de retorno porque se programa más rápido. Más rápido, sí. Más seguro, no. Un paso de verificación de 5 segundos siempre gana a un hilo de correos con soporte más tarde.

Si Payora ofrece una devolución firmada o un mecanismo de confirmación de servidor a servidor, úsalo junto con la consulta de estado. Así tendrás dos comprobaciones: una desde el flujo del cliente y otra desde el flujo del servidor. Si tu implementación necesita una verificación de firma paso a paso, consulta cómo probar un pago cripto para ver el tipo de disciplina de validación que compensa antes del lanzamiento.

Solo marca el pedido como pagado cuando el servidor esté de acuerdo. No después de que lo diga el cliente. No después de que lo diga el navegador. Tu base de datos debe reflejar el estado de pago que confirma Payora, porque ese es el estado en el que confiarán luego tus equipos de logística y contabilidad.

7. Guarda el registro del pago y gestiona los envíos duplicados

Guarda en tu base de datos la referencia de la transacción de Payora, el ID del pedido local, el importe, la moneda y el estado final. Hazlo en una sola escritura si puedes. Más adelante, cuando un cliente te escriba diciendo “he pagado dos veces”, agradecerás un registro limpio y no tres actualizaciones a medio terminar.

Los envíos duplicados ocurren por razones normales. El cliente hace clic dos veces. Se usa el botón de atrás. El navegador reintenta la solicitud. Tu código PHP debe detectar que el pedido ya tiene una referencia de Payora y negarse a crear un segundo pago para el mismo pedido, salvo que el primero haya fallado o caducado. Ese es el núcleo de la idempotencia.

Una regla sencilla funciona bien: un pedido local, una transacción activa de Payora. Si llega una segunda solicitud para el mismo pedido mientras la primera sigue pendiente, muestra el enlace de pago existente en Payora en lugar de crear uno nuevo. Si el pedido ya está pagado, no hagas nada. En silencio. Ese silencio es una ventaja.

Haz que las columnas de tu base de datos sean específicas. Por ejemplo, guarda payora_reference, payment_status, paid_at y last_checked_at. Estos campos ayudan a soporte, contabilidad y depuración. Si luego necesitas conciliar un pago, esos cuatro campos pueden responder la mayoría de las preguntas sin pasar una hora buscando en los registros.

Si estás construyendo un flujo de facturación para clientes en lugar de un proceso de compra de tienda, el artículo sobre pasarelas de pago cripto para freelancers también puede ayudarte con la misma lógica de registro, especialmente cuando los números de factura importan más que los carritos.

8. Prueba el flujo completo en una copia de staging del sitio

Antes de ponerlo en producción, clona el sitio en staging y prueba toda la cadena: creación del pedido, redirección a Payora, página de retorno, verificación del servidor y manejo de clics duplicados. Si solo pruebas la redirección, habrás probado solo un tercio del problema.

Ejecuta al menos estas comprobaciones:

• Crea un pedido nuevo y confirma que se genera la solicitud de pago de Payora.
• Refresca la página de retorno 2 veces y confirma que el pedido no vuelve a cambiar.
• Envía el formulario de pago dos veces y verifica que solo exista 1 transacción activa.
• Fuerza un resultado pendiente o fallido y confirma que el pedido sigue sin pagarse.
• Comprueba que la referencia de Payora guardada coincida con el registro de la base de datos.

Prueba con la misma versión de PHP y la misma configuración del servidor que piensas usar en producción. Un flujo que funciona en un portátil local puede fallar en un servidor de producción con una configuración SSL más estricta o un ajuste de cURL distinto. No es raro. Pasa.

Una última prueba práctica: abre el pedido en una ventana de incógnito, completa el pago y luego abre la misma URL de retorno desde un segundo navegador. Tu app no debería emitir una segunda actualización de pago. Si lo hace, arréglalo antes del lanzamiento. Sin excepciones.

Para equipos que venden rutas de pago con USDC junto con otros métodos de pago, las notas en cómo aceptar pagos USDC pueden ayudarte a comparar las expectativas de los clientes antes de llevar el flujo PHP a producción.

Eso es lo último que debes comprobar: el mismo pedido debe sobrevivir a una redirección, un refresco y una confirmación del servidor sin desincronizarse. Si lo hace, tu proceso de pago PHP personalizado y tu pasarela de pago Payora PHP estarán listos para el primer pago real.