Integración Proxy - SiteMinder

  1. Introducción
  2. Tipos de reservas
  3. Tokenización de la información de tarjeta de una reserva
  4. Transformación de los datos de tarjeta
  5. Endpoint y datos de la llamada
  6. Respuesta error
  7. Envío de API-KEYS
  8. Entorno de desarrollo

Introducción

El servicio Proxy de PAYCOMET con SiteMinder permite tokenizar las tarjetas registradas en las reservas hoteleras y verificar que el formato de los datos de tarjeta recibidos en las mismas son correctos. Para poder acceder a este tipo de integración, se deberá contar previamente con la integración de la API de SiteMinder, 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_code) y el criterio indicad en el campo (selection_criteria).

Ejemplo de información contenida en una reserva:



<OTA_ResRetrieveRS>
	xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:32:47+08:00" EchoToken="echo-abc123">
	<Success/>
	<ReservationsList>
		<HotelReservation CreateDateTime="2007-12-09T08:51:45.000+0000" ResStatus="Book">
			<POS>
				<Source>
					<RequestorID Type="22" ID="SITEMINDER"/>
					<BookingChannel Primary="true" Type="7">
						<CompanyName Code="WTF">Wotif</CompanyName>
					</BookingChannel>
				</Source>
			</POS>
			<UniqueID Type="14" ID="WTF-001"/>
			<UniqueID Type="16" ID="1243132" ID_Context="MESSAGE_UNIQUE_ID"/>
			<RoomStays>
				<RoomStay>
					<RoomRates>
						<RoomRate RoomTypeCode="DR" RatePlanCode="RAC" NumberOfUnits="1">
							<Rates>
								<Rate UnitMultiplier="3" RateTimeUnit="Day" EffectiveDate="2013-03-12" ExpireDate="2013-03-15">
									<Total AmountAfterTax="50.00" CurrencyCode="USD"/>
								</Rate>
							</Rates>
						</RoomRate>
					</RoomRates>
					<GuestCounts>
						<GuestCount AgeQualifyingCode="10" Count="1"/>
					</GuestCounts>
					<TimeSpan Start="2013-03-12" End="2013-03-15"/>
					<Total AmountAfterTax="150.00" CurrencyCode="USD"/>
					<BasicPropertyInfo HotelCode="10107"/>
					<ResGuestRPHs>
						<ResGuestRPH RPH="1"/>
					</ResGuestRPHs>
				</RoomStay>
			</RoomStays>
			<ResGuests>
				<ResGuest ResGuestRPH="1" ArrivalTime="10:30:00">
					<Profiles>
						<ProfileInfo>
							<UniqueID Type="16" ID="12345" ID_Context="CHANNEL"/>
							<Profile ProfileType="1">
								<Customer>
									<PersonName>
										<GivenName>James</GivenName>
										<Surname>Bond</Surname>
									</PersonName>
								</Customer>
							</Profile>
						</ProfileInfo>
					</Profiles>
				</ResGuest>
			</ResGuests>
			<ResGlobalInfo>
				<Guarantee>
					<GuaranteesAccepted>
						<GuaranteeAccepted>
							<PaymentCard CardCode="VI" CardType="1" CardNumber="4444444444444444" ExpireDate="1114">
								<CardHolderName>Bruce Wayne</CardHolderName>
							</PaymentCard>
						</GuaranteeAccepted>
					</GuaranteesAccepted>
				</Guarantee>
				<DepositPayments>
					<GuaranteePayment>
						<AmountPercent Amount="30.00" CurrencyCode="USD" Percent="20.00"/>
						<Description>
							<Text>20% Deposit</Text>
						</Description>
					</GuaranteePayment>
				</DepositPayments>
				<Total AmountAfterTax="150.00" CurrencyCode="USD"/>
				<HotelReservationIDs>
					<HotelReservationID ResID_Type="14" ResID_Value="RES_3243525"/>
				</HotelReservationIDs>
			</ResGlobalInfo>
		</HotelReservation>
	</ReservationsList>
</OTA_ResRetrieveRS>

Los procesos que se describen a continuación se realizan para cada una de las reservas contenidas en el nodo HotelReservation

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. 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, 444444******4444. 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, en la reserva anterior, una vez tokenizada la información de la tarjeta, el nodo <HotelReservation> quedará de la siguiente manera:



<HotelReservation>
    ...
	<ResGlobalInfo>
		<Guarantee>
			<GuaranteesAccepted>
				<GuaranteeAccepted>
					<PaymentCard CardCode="VI" CardType="1" CardNumber="444444******4444" ExpireDate="1114">
						<CardHolderName>Bruce Wayne</CardHolderName>
					</PaymentCard>
				</GuaranteeAccepted>
			</GuaranteesAccepted>
		</Guarantee>
		<PaycometResponse>			
			<iduser>99999999</iduser>
			<tokenuser>XxXxXxXxXxXxX</tokenuser>
		</PaycometResponse>
	</ResGlobalInfo>
</HotelReservation>

En caso de error en la tokenización, no aparecerán los elementos iduser / tokenuser y se añadirá un elemento ds_error_id



<HotelReservation>
    ...
	<ResGlobalInfo>
		<Guarantee>
			<GuaranteesAccepted>
				<GuaranteeAccepted>
					<PaymentCard CardCode="VI" CardType="1" CardNumber="444444******4444" ExpireDate="1114">
						<CardHolderName>Bruce Wayne</CardHolderName>
					</PaymentCard>
				</GuaranteeAccepted>
			</GuaranteesAccepted>
		</Guarantee>	
	</ResGlobalInfo>
	...
    <ds_error_id>9999</iduser>
</HotelReservation>

Se informará también dentro del HotelReservation, en el caso de que existan datos de tarjeta, de si la tarjeta pertenece a la categoría B2B; posibles valores 1/0



<HotelReservation>
    ...
	<ResGlobalInfo>
		<Guarantee>
			<GuaranteesAccepted>
				<GuaranteeAccepted>
					<PaymentCard CardCode="VI" CardType="1" CardNumber="444444******4444" ExpireDate="1114">
						<CardHolderName>Bruce Wayne</CardHolderName>
					</PaymentCard>
				</GuaranteeAccepted>
			</GuaranteesAccepted>
		</Guarantee>
		<PaycometResponse>			
			<iduser>99999999</iduser>
			<tokenuser>XxXxXxXxXxXxX</tokenuser>
		</PaycometResponse>
	</ResGlobalInfo>	
</HotelReservation>

En el caso de que una reserva no contenga datos de tarjeta, se devolverá tal y como fue recibida.

Endpoint y datos de la llamada

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

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

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 SiteMinder</username>
                <password>vuestra password SiteMinder</password>
				<requestor_id>Identificador</requestor_id>
				<requestor_type>Fijo 22</requestor_type>
                <hotel_code>id del Hotel</hotel_code>
                <selection_criteria>Undelivered</selection_criteria>
            </request>
        </xml>
        <url>URL SiteMinder a la que se debe realizar la llamada</url>
    </booking>
    <paytpv>
        <ds_merchant_code>código de comercio en PAYTPV</ds_merchant_code>
        <ds_merchant_terminal>número de terminal en PAYTPV</ds_merchant_terminal>
    </paytpv>
</root>

Respuesta error

Si se produce un error en los datos de la petición o al acceder a SiteMinder, se enviará un mensaje de error, con la consideración siguiente: si el error se produce en la llamada a PAYCOMET (credenciales, formato) o en la llamada desde PAYCOMET a SiteMinder (timeout, sin respuesta, etc) se enviará un nodo con el codigo error (ErrorId-PAYTPV). Una vez superado ese punto, si se produce un error se devolverá exactamente lo devuelto por SiteMinder:

Error PAYCOMET anterior a la llamada a SiteMinder



<?xml version="1.0" standalone="yes"?>
<reservations>
<fault code="1040-PAYTPV" string="Field DS_MERCHANT_MERCHANTCODE incorrect" />
</reservations>

Error devuelto por SiteMinder



<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Header />
	<SOAP-ENV:Body>
		<OTA_ResRetrieveRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0"
			TimeStamp="2021-08-17T12:42:28+00:00" EchoToken="echos-abc123">
			<Errors>
				<Error Type="4">Authentication failed - PMS received request with invalid username/password</Error>
			</Errors>
		</OTA_ResRetrieveRS>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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 “API KEY” en elbotó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 SiteMinder hoteles y reservas de prueba que permitan verificar el proceso completo.