Integración Proxy - Booking

  1. Introducción
  2. Tipos de reservas
  3. Estados de reservas
  4. Tokenización de la información de tarjeta de una reserva
  5. Transformación de los datos de tarjeta
  6. Endpoint y datos de la llamada
  7. Respuesta error
  8. Envío de API-KEYS
  9. Entorno de desarrollo
  10. Opción last_change
  11. Llamada sin parámetros

Introducción

El servicio Proxy de PAYCOMET con Booking permite tokenizar las tarjetas enviadas en las reservas hoteleras y verificar que los datos de tarjeta enviados son correctos. Para poder acceder a este tipo de integración, se deberá contar previamente con la integración de la API de Booking (https://secure-supply-xml.booking.com -- para servers PCI), en la que se envían los datos de la reserva ya que la respuesta incluirá todos los datos de la reserva seleccionada y se añadirán y/o transformarán los relativos a la tarjeta.

Tipos de reservas

Los tipos de reservas que se tratan en esta integración son aquellas que pueden recuperarse mediante identificador de hotel (hotel_id) e identificador de reserva (id). Para cada reserva debe realizarse una llamada con estos dos identificadores.

Estados de reservas

Los estados de reserva que se tratan por defecto son:

  • new
  • modified
  • upgrade

Si además, tu integración necesita tratar el estado 'cancelled', por favor, comunicádnoslo para poder configurar correctamente el producto/terminal.



<reservations>
	<reservation>
		<commissionamount>99.99</commissionamount>
		<currencycode>xxx</currencycode>
		<customer>
		<address></address>
		<cc_cvc>999</cc_cvc>
		<cc_expiration_date>99/9999</cc_expiration_date>
		<cc_name>xxxxxxxxxxxxxxxxxx</cc_name>
		<cc_number>9999999999999999</cc_number>
		<cc_type>xxxxxxxx</cc_type>
		<city>xxxxxxxxxxxxxxx<city>
		<company></company>
		<countrycode>xxxxxxxx</countrycode>
		<dc_issue_number></dc_issue_number>
		<dc_start_date></dc_start_date>
		<email>xxxxxxxxxxxxxxxxxxxxx</email>
		<first_name>xxxxxxxx</first_name>
		<last_name>xxxxxxxx</last_name>
		<remarks>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</remarks>
		<telephone>999999999999999</telephone>
		<zip></zip>
		</customer>
		<date>9999-99-99</date>
		<hotel_id>9999999</hotel_id>
		<hotel_name>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</hotel_name>
		<id>9999999999</id>
		<room>
			<arrival_date>9999-99-99</arrival_date>
			<commissionamount>99.99</commissionamount>
			<currencycode>EUR</currencycode>
			<departure_date>9999-99-99</departure_date>
			<extra_info>xxxxxx</extra_info>
			<facilities>xxxxxxxxx</facilities>
			<guest_name>xxxxxxxxxxxx</guest_name>
			<id>999999999</id>
			<info>xxxxxxxxxxxxxxxxx</info>
			<max_children>9</max_children>
			<meal_plan>xxxxxxxxxxxxx</meal_plan>
			<name>xxxxxxxxxxxxxx</name>
			<numberofguests>1</numberofguests>
			<price date="9999-99-99"
			genius_rate="no"
			rate_id="9999999">99.99</price>
			<price date="9999-99-99"
			genius_rate="no"
			rate_id="9999999">99.99</price>
			<remarks></remarks>
			<roomreservation_id>9999999999</roomreservation_id>
			<smoking>9</smoking>
			<totalprice>999</totalprice>
		</room>
		<status>new</status>
		<time>99:99:99</time>
		<totalprice>999</totalprice>
	</reservation>
	</reservations>
	<!-- RUID:
   [Umxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxEQ] -->

Tokenización de la información de tarjeta de una reserva

Al recibir una reserva, si esta contiene datos de tarjeta (existen reservas que no pueden tratarse ya que no los contienen), se intenta realizar una tokenización de los mismos. Si todos los datos necesarios están presentes y se consigue realizar correctamente, al nodo se le añadirán los elementos

  • iduser
  • tokenuser

que representan la tarjeta tokenizada y que serán necesarios para operaciones posteriores. A partir de la versión 1.5 se permite tokenizar aunque no llegue cvc. Por favor, solicítanos la habilitación de esta opción.

Transformación de los datos de tarjeta

En la respuesta devuelta, la tarjeta aparecerá enmascarada, 456789******1234. Le fecha de caducidad se devolverá tal y como aparece en la reserva y el código CVC2 se eliminará y no llegará. Por lo tanto, la reserva anterior, una vez tokenizada la información de la tarjeta el nodo quedará de la siguiente manera:



	<customer>
		<address></address>
		<cc_expiration_date>99/9999</cc_expiration_date>
		<cc_name>xxxxxxxxxxxxxxxxxx</cc_name>
		<cc_number>999999******9999</cc_number>
		<cc_type>xxxxxxxx</cc_type>
		<city>xxxxxxxxxxxxxxx</city>
		<company></company>
		<countrycode>xxxxxxxx</countrycode>
		<dc_issue_number></dc_issue_number>
		<dc_start_date></dc_start_date>
		<email>xxxxxxxxxxxxxxxxxxxxx</email>
		<first_name>xxxxxxxx</first_name>
		<last_name>xxxxxxxx</last_name>
		<remarks>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</remarks>
		<telephone>999999999999999</telephone>
		<zip></zip>
		<iduser>999999999</iduser>
		<tokenuser>XXXXXXXXXXXXXXX</tokenuser>
	</customer>

En caso de error en la preautoriación/cancelación también elemento ds_error_id



<customer>
…
	<ds_error_id>999999999</ds_error_id>
…
</customer>

Se informará también dentro del nodo customer, en el caso de que existan datos de tarjeta, de si la tarjeta pertenece a la categoría B2B. <b2b>1/0</b2b>

Endpoint y datos de la llamada

El endpoint al que hay que realizar la petición es:

- https://eclipse.paycomet.com/api/v1/booking

El tipo de petición que espera es un post con un parámetro 'xml' con la siguiente estructura:



<root>
	<booking>
		<xml>
			<request>
				<username>vuestro usuario Booking</username>
				<password>vuestra Password Booking</password>
				<hotel_id>id del Hotel</hotel_id>
				<id>id de la Reserva</id>
			</request>
		</xml>
		<url>URL Booking a la que se debe realizar la llamada</url>
	</booking>
	<paytpv>
		<ds_merchant_code>código de comercio en PAYCOMET</ds_merchant_code>
		<ds_merchant_terminal>número de terminal en PAYCOMET</ds_merchant_terminal>
	</paytpv>
</root>

Respuesta error

Si se produce un error en los datos de la petición o al acceder a Booking, se enviará la siguiente respuesta:



<?xml version="1.0" standalone="yes"?>
<reservations>
	<fault code="9999-PAYTPV" string="The type of operation requested doesnt exist" />
</reservations>

Donde 9999 indicará el código de error observado.

Envío de API-KEYS

En el nuevo Endpoint el método de autenticación ha sido actualizado de una restricción por IP al envío una cabecera específica con el API-KEY generado para el producto/productos en cuestión.

La cabecera HTTP debe tener el siguiente nombre:

PAYCOMET-API-TOKEN

El valor de la cabecera debe ser la clave API-KEY generada a través del panel de control de cliente: “Configuración” -> “Desarrolladores” -> “API Keys”.

Una vez en el panel de gestión de API Keys debe crearse una nueva “Nueva API Key” en el botón superior derecho y asignarle un nombre.

En el siguiente panel debe copiarse la API KEY ya que solo aparecerá en una ocasión. Por motivos de seguridad, no volverá a mostrarse. Los permisos de las API KEYS pueden asignarse a uno o varios productos, e incluso a todos los de una cuenta mediante los selectores:

Para el producto que vaya a utilizarse para presentar las reservas de la OTA (Online Travel Agency) y donde quedarán tokenizadas las tarjetas será necesario asignarle permisos específicos de “Permiso de proxy”.

Una vez finalizadas las gestiones de API Keys, el valor generado a la API Key deberá enviarse en la cabecera como método de autenticación.

Entorno de desarrollo

Este desarrollo no cuenta con un sandbox en el que puedan realizarse llamadas con datos de prueba. Las llamadas al script son todas reales. Lo que debe hacerse para poder probar la integración es crear en Booking hoteles y reservas de prueba que permitan verificar el proceso completo.

Opción last_change

Para los comercios que no dispongan de la opción de identificar las reservas por <id>, existe la posibilidad de solicitarlas mediante la opción <last_change>. Se devolverán todas las reservas pendientes desde la fecha indicada en dicho elemento se realizarán las transformaciones de datos de tarjeta correspondientes. También se tokenizarán para su posterior uso.

El límite máximo del intervalo de tiempo a consultar es de 24 horas.

Llamada sin parámetros

El servicio Proxy de PAYCOMET con Booking permite actualmente recibir peticiones que no incluyan ni el <id> de la reserva, ni la opción <last_change>. En caso de no enviar ninguno de estos dos datos, PAYCOMET identificará la petición como una llamada sin parámetros, y el servicio devolverá todas las reservas que no se hubiesen obtenido hasta ese momento. Al igual que en la opción last_change, se realizarán las transformaciones necesarias en los datos de tarjeta y se tokenizarán para posibilitar su uso en otro momento.