API de pagos de viajes
API de pasarela de pago para reservas de viajes: del checkout al reembolso
Una API de pasarela de pago permite que tu web de reservas cobre al viajero sin tocar nunca la tarjeta. Esta página recorre las llamadas de un pago con tarjeta, los estados por los que pasa un pago, por qué los pagos de viajes son más difíciles que los del comercio minorista y cómo PHPTRAVELS conecta tu flujo de reserva con la pasarela que elijas.
- Sesión, 3-D Secure, captura
- Todos los estados del pago
- Tarjetas, monederos, banco, crédito
- Sin datos de tarjeta en tu servidor
Cómo funcionan las llamadas
Un pago con tarjeta, llamada a llamada
Una API de pasarela de pago es un conjunto de servicios web que una empresa de pagos abre a los comercios. Tu servidor le pide crear un pago por un importe y una moneda, el viajero introduce la tarjeta en el formulario de la propia pasarela, y esta habla con la red de tarjetas y con el banco emisor. Tu servidor nunca ve el número de la tarjeta; recibe un ID de pago y un estado.
Intervienen cuatro partes. El diagrama las muestra como columnas y cada mensaje como una flecha numerada. Los nombres cambian de una pasarela a otra (payment intent, sesión, pedido, cargo), pero la secuencia es la misma.
La flecha discontinua es un webhook: la pasarela llama a tu servidor por su cuenta, así que el pago actualiza la reserva aunque el viajero cierre el navegador. La página Integración de pasarelas de pago explica cómo se vincula cada paso a una reserva en PHPTRAVELS.
- Viajero
- Tu web
- Pasarela
- Red de tarjetas / banco
01CheckoutViajero Tu web
El viajero revisa el viaje y pulsa Pagar. La reserva queda retenida con el proveedor, aún sin confirmar.
02Crear el payment intent o la sesiónTu web Pasarela
Tu servidor envía importe, moneda, referencia de reserva y una clave de idempotencia con su clave API secreta. La pasarela devuelve un ID de pago.
03Campos alojados o redirecciónPasarela Viajero
El formulario de tarjeta lo sirve la pasarela, dentro de tu página o en la suya, de modo que los datos de la tarjeta van directos a ella.
043-D SecureRed de tarjetas / banco Viajero
Si el banco emisor lo pide, el viajero confirma el pago en la app del banco o con un código de un solo uso.
05AutorizarPasarela Red de tarjetas / banco
La pasarela pide al emisor, a través de la red de tarjetas, que apruebe el importe.
06Aprobado, fondos retenidosRed de tarjetas / banco Pasarela
El emisor reserva el dinero en la tarjeta. Todavía no se ha movido nada.
07Resultado a tu webPasarela Tu web
El viajero vuelve a tu web con el ID de pago. Tu servidor lee el estado desde la API y confirma la reserva con el proveedor.
08CapturaTu web Pasarela
Cuando el proveedor confirma, tu servidor captura el importe completo o uno menor. Muchas pasarelas también pueden capturar al instante.
09WebhookPasarela Tu webEnviado por la pasarela por su cuenta
La pasarela envía a tu endpoint un evento firmado (pago capturado, reembolsado, disputado). Tu servidor comprueba la firma y actualiza la reserva.
Estados del pago
La vida de un pago como máquina de estados
Toda API de pasarela informa de un estado para cada pago. Las palabras varían, pero se reducen a los mismos pocos estados, y tu lógica de reservas debe reaccionar a cada uno.
created
Creado
El pago existe con importe y moneda, a la espera del viajero.
failedFinal
Fallido
Rechazado, 3-D Secure sin completar o abandonado. No se cobra nada.
authorized
Autorizado
El emisor aprobó el importe y lo retiene en la tarjeta.
voidedFinal
Anulado
La retención se cancela antes de la captura, así que el viajero nunca paga.
captured
Capturado
El dinero está cobrado y se liquidará en tu cuenta de comercio.
partially_refundedFinal
Reembolsado parcialmente
Se devuelve una parte del importe capturado, por ejemplo tras una penalización por cancelación.
refundedFinal
Reembolsado
Todo el importe capturado vuelve a la tarjeta.
Una autorización no dura para siempre: si no se captura a tiempo, la retención caduca y el banco libera el dinero. Un pago reembolsado parcialmente puede seguir reembolsándose, hasta el importe capturado.
Por qué viajar es más difícil
Por qué los pagos de viajes son distintos
Una tienda vende lo que tiene en stock. Un vendedor de viajes cobra por una reserva que un proveedor aún debe confirmar, a menudo meses antes del viaje. La API de pagos tiene que encajar con eso.
01
Autorizar ahora, capturar después
Los hoteles bajo petición, las tarifas de grupo y las excursiones se confirman horas o días después del pedido. Autorizar primero y capturar al confirmar evita cobrar una reserva que nunca llega a existir.
02
El proveedor todavía puede decir que no
Una tarifa puede agotarse entre el pago y la emisión. Con una autorización, el dinero se libera con una anulación; tras la captura pasa a ser un reembolso.
03
Reembolsos parciales tras gastos de cancelación
Cancelar una estancia o un billete suele conllevar una penalización. La llamada de reembolso envía un importe menor contra el pago original, tantas veces como exijan las condiciones.
04
Multidivisa
Los viajeros pagan en su moneda mientras los proveedores facturan en la suya. La pasarela debe admitir la moneda de presentación, y tus registros deben guardar ambos importes.
05
Controles antifraude en importes altos
Billetes para mañana, para otra persona y pagados con una tarjeta nueva son un patrón clásico de fraude. 3-D Secure, la puntuación de riesgo de la pasarela y una cola de revisión manual protegen los pedidos de alto valor.
06
Contracargos meses después
Las disputas suelen llegar tras el viaje. Guarda juntos el resultado de la autenticación, los documentos de la reserva y los eventos de la pasarela para poder responder con pruebas.
Métodos de pago
Qué formas de pago cubre una API de pasarela de pago
Las tarjetas son solo una opción. Viajeros y agentes pagan de maneras distintas, y cada una se reembolsa de forma diferente.
| Método | Qué es | Cuándo llega el dinero | Reembolsos |
|---|---|---|---|
| Tarjetas | Tarjetas de débito y crédito a través de la pasarela, con 3-D Secure cuando el emisor lo exige. | Autorizadas en el checkout; capturadas de inmediato o cuando el proveedor confirma. | Reembolso total o parcial a la misma tarjeta mediante la API. |
| Monederos digitales | Cuentas de monedero que admite la pasarela, como PayPal o un monedero móvil con una tarjeta tokenizada. | En el checkout, cuando el viajero aprueba en el monedero. | De vuelta al monedero o a la tarjeta que hay detrás, a través de la pasarela. |
| Transferencia bancaria | El viajero o el agente envía dinero a tu cuenta bancaria y el pago se registra en la reserva. | Días después; la reserva espera hasta que tu equipo confirme la recepción. | Se devuelve por transferencia, fuera de la pasarela. |
| Pagar después | La reserva se hace ahora y se paga más tarde; tu equipo registra el pago cuando llega. | Después de la reserva, cuando el viajero paga. | Solo se devuelve lo que se pagó realmente. |
| Monedero o crédito de agente B2B | Los subagentes pagan con un saldo que cargan por adelantado o con un límite de crédito que tú les concedes. | Se descuenta al reservar; depósitos y crédito se liquidan según tus condiciones. | Se abona de vuelta al saldo del agente. |
La transferencia bancaria, pagar después y el saldo del monedero son opciones de liquidación de la propia plataforma, no pasarelas. Los saldos y límites de crédito de los agentes se explican en la página Monedero B2B para agentes; los pagos bancarios, en la página Pagos por transferencia bancaria.
Listo en PHPTRAVELS
API de pasarela de pago ya conectadas
Estas pasarelas ya están conectadas a PHPTRAVELS. Abres una cuenta de comercio con el proveedor, introduces tus claves API en el administrador, pruebas en su entorno de pruebas y sales en producción. La lista es la actual de nuestro directorio de integraciones.
StripeGuía de integración
PayPalGuía de integración
xMoney
Fawaterk
Cashfree
Paystack
Flutterwave
Adyen
MyFatoorah
SSLcommerz
Razorpay- Todas las integraciones de pago
Las comisiones y la aprobación como comercio se acuerdan con la empresa de pagos, no con PHPTRAVELS. Una pasarela que no figure aquí puede añadirse como Integración de API personalizada, y la página Integración de pasarelas de pago explica cómo se configura cada una.
Seguridad
Mantener los datos de tarjeta fuera de tu sistema
El número de tarjeta más seguro es el que tu servidor nunca recibe. Una API de pasarela de pago está diseñada para que no tenga que recibirlo.
Nunca guardes números de tarjeta
Los datos de la tarjeta van a la pasarela, que devuelve un token o un ID de pago. Tu base de datos guarda esa referencia, nunca el número de tarjeta ni el código de seguridad.
Los campos alojados y las redirecciones reducen el alcance de PCI DSS
PCI DSS se aplica a quien maneja datos de tarjeta. Cuando el formulario es la página de la pasarela o campos incrustados, mucho menos de tu sistema entra en el alcance. Tu adquirente confirma qué autoevaluación te corresponde.
Webhooks verificados por firma
Cada webhook lleva una firma hecha con un secreto compartido. Tu servidor la recalcula y rechaza cualquier evento que no coincida, así nadie puede falsificar una reserva pagada.
Las claves secretas se quedan en el servidor
El navegador solo recibe una clave pública. La clave secreta que crea pagos y reembolsos vive en la configuración de tu servidor, y cada petición lleva una clave de idempotencia para que un reintento nunca cobre dos veces.
1$payload = file_get_contents("php://input"); 2$signature = $_SERVER["HTTP_X_SIGNATURE"] ?? ""; 3$expected = hash_hmac("sha256", $payload, $webhookSecret); 4 5if (!hash_equals($expected, $signature)) { 6 http_response_code(400); exit; // reject 7} 8$event = json_decode($payload, true); 9if (alreadyHandled($event["id"])) exit; // repeat delivery10updateBooking($event["data"]["metadata"]["booking_ref"], $event["type"]);
Ejemplo genérico. Los nombres de las cabeceras y el método de firma dependen de la pasarela que elijas.
PHPTRAVELS es software autoalojado, por lo que el cumplimiento de PCI DSS se evalúa para tu negocio y tu servidor, no solo para el software.
Mira una reserva pagada, capturada y reembolsada
Reserva un viaje en la demo en vivo y sigue el pago en el administrador. En el plan Enterprise, PHPTRAVELS también te da su propia REST API y webhooks para tus apps y socios.
¿Piensas vender también vuelos? La página API de vuelos explica el lado del proveedor, y APIs de viajes lista todas las API que conecta PHPTRAVELS.
Es un conjunto de servicios web que ofrece una empresa de pagos para que una web pueda crear pagos, enviar la tarjeta al banco para su aprobación, capturar el dinero, emitir reembolsos y recibir actualizaciones de estado por webhook, sin guardar ella misma datos de tarjeta.
La pasarela es la parte con la que habla tu web: recoge la tarjeta de forma segura y transmite la petición. El procesador lleva la transacción por las redes de tarjetas hasta el banco emisor. Muchos proveedores ofrecen ambos como un solo servicio.
La que apruebe tu negocio, admita los países, monedas y métodos de pago de tus clientes, y ofrezca autorización y captura por separado además de reembolsos parciales. Muchas agencias combinan una pasarela global de tarjetas con una regional.
Autorizar reserva el importe en la tarjeta del viajero; capturar lo cobra. Separar ambos pasos permite cobrar solo cuando el proveedor confirma la reserva, y anular la retención si no lo hace.
En muchas regiones, como el Espacio Económico Europeo y el Reino Unido, la autenticación reforzada del cliente es obligatoria para la mayoría de los pagos con tarjeta en línea, y 3-D Secure es la forma en que las tarjetas la cumplen. La API de la pasarela gestiona el desafío; tu flujo de reserva espera el resultado.
Por sí sola no. Usar los campos alojados o la página de pago de la pasarela mantiene los datos de tarjeta fuera de tu servidor y reduce tu alcance PCI DSS, pero aun así debes completar la evaluación que te pida tu adquirente.
Sí, si la pasarela admite reembolsos parciales, lo que hacen la mayoría de las pasarelas de tarjeta. Envías un reembolso por un importe menor contra el pago original, por ejemplo el precio menos una penalización por cancelación.
No. Abres una cuenta de comercio con la pasarela que elijas y acuerdas con ella las comisiones. PHPTRAVELS conecta tu plataforma de reservas a esa cuenta con las claves API que introduces en el administrador.
Sí. Cualquier pasarela con una API documentada puede añadirse como integración personalizada, y como el código fuente está incluido, tus desarrolladores también pueden ampliar el flujo de pago.
Sigue explorando
Más sobre la plataforma
- Integración de pasarelas de pagoCheckout, 3D Secure, reembolsos y webhooks
- Pagos con StripeCobro con tarjeta y monedero, reembolsos y pagos
- Pagos con PayPalPago con PayPal para vuelos, hoteles y tours
- Monedero B2B para agentesDepósitos, límites de crédito y un libro mayor por agente
- APIs de viajesAPIs de GDS, hoteles, tours, coches y pagos
- API de vuelosAPI de vuelos GDS, NDC y de consolidadores en una plataforma