Proxy Integration - SiteMinder

  1. Introduction
  2. Types of reservations
  3. Tokenization of the card information of a reservation
  4. Card data transformation
  5. Endpoint and call data
  6. Error response
  7. Sending API-KEYS
  8. Development environment

Introduction

The PAYCOMET Proxy service with SiteMinder allows to tokenize the cards registered in the hotel reservations and verify that the format of the card data received in them is correct. In order to access this type of integration, you must previously have the SiteMinder API integration, in which the reservation data is sent since the The answer will include all the data of the selected reservation and the data relating to the card will be added and / or transformed

Types of reservations

The types of reservations that are treated in this integration are those that can be retrieved by hotel identifier (hotel_code) and those with (selection_criteria).

Example of information contained in a reservation:



<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>

The processes described below are carried out for each of the reservations contained in the HotelReservation node

Tokenization of the card information of a reservation

Upon receiving a reservation, if it contains card data (there are reservations that cannot be processed since they do not contain them), an attempt is made to tokenize them. If all the necessary data are present and it is successful, the node will be added the elements

  • iduser
  • tokenuser

that represent the tokenized card and that will be necessary for subsequent operations. Tokenize is allowed even if cvc does not arrive. Please, ask us to enable this option

Card data transformation

In the returned response, the card will appear masked, 444444******4444. The expiration date will be returned as it appears in the reservation and the CVC2 code will be removed and will not arrive. Therefore, in the previous reservation, once the card information is tokenized, the node & lt; HotelReservation & gt; will be as follows:



<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>

In case of an error in the tokenization, the iduser / tokenuser elements will not appear and a ds_error_id element will be added



<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>

It will also be informed within the HotelReservation node, in the event that there is card data, whether the card belongs to the B2B category; possible values 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>

In the event that a reservation does not contain card details, it will be returned as received.

Endpoint and call data

The script to which the request must be made is:

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

The type of request that it expects is a post with an 'xml' parameter with the following structure:



<root>
    <booking>
        <xml>
            <request>
                <username>vuestro usuario SiteMinder</username>
                <password>vuestra password SiteMinder</password>
				<requestor_id>Identifier</requestor_id>
				<requestor_type>Fixed at 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>

Error response

If an error occurs in the request data or when accessing SiteMinder, an error message will be sent the same as the one currently returned by SiteMinder, with the following consideration: if the error occurs in the call to PAYCOMET (credentials, format) or in the call from PAYCOMET to SiteMinder (timeout, no response, etc) the ErrorId element is replaced by ErrorId-PAYTPV, indicating that there has been no connection establishment with SiteMinder. Once that point is passed, if an error occurs, exactly what is returned by SiteMinder (with ErrorId element) will be returned:

PAYCOMET error prior to calling SiteMinder



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

Error returned by SiteMinder



<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetOrdersResponse xmlns="XmlServices">
            <GetOrdersResult>
                <Status>
                    <Success>false</Success>
                    <ErrorMsg>Invalid username or
                        password.</ErrorMsg>
                    <ErrorId>1001</ErrorId>
                    <TimeStamp>2017-09-
                        07T13:53:23.2633149+02:00</TimeStamp>
                </Status>
            </GetOrdersResult>
        </GetOrdersResponse>
    </soap:Body>
</soap:Envelope>

Sending API-KEYS

In the new Endpoint, the authentication method has been updated from a restriction by IP to sending a specific header with the API-KEY generated for the product / products in question.

The HTTP header must have the following name:

PAYCOMET-API-TOKEN

The value of the header must be the API-KEY generated through the customer control panel: “Configuration” -> Developers -> “API Keys”.

Once in the API Keys management panel, a new “API KEY” must be created in the upper right button and assigned a name.

In the next panel, the API KEY must be copied since it will only appear once. For security reasons, it will not be shown again. The permissions of the API KEYS can be assigned to one or more products, and even to all of an account using the selectors:

For the product that is going to be used to present the reservations of the OTA (Online Travel Agency) and where the cards will be tokenized, it will be necessary to assign specific permissions of 'Proxy permission' .

Once the API Keys procedures have been completed, the value generated to the API Key must be sent in the header as an authentication method.

Development environment

This development does not have a sandbox where calls can be made with test data. The calls to the script are all real. In order to test the integration, what must be done is to create test hotels and reservations in SiteMinder that allow the complete process to be verified.