Proxy Integration - Yieldplanet
Introduction
The PAYCOMET Proxy service with YieldPlanet 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 YieldPlanet API integration (at the time of generating this XML Services - YieldPlanet API 3.0 version), 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_id) and those with status changes since a date (status_changed_since).
Example of information contained in a reservation:
<?xml version="1.0" encoding="utf-8"?> <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"> <GetOrdersResponse xmlns="XmlServices"> <GetOrdersResult> <Status> <Success>true</Success> <ErrorId>0</ErrorId> <TimeStamp>2017-09-07T14:05:52.0162772+02:00</TimeStamp> </Status> <Orders> <Order> <Id>34192783</Id> <HotelId>3</HotelId> <PartnerId>719</PartnerId> <PartnerName>Booking.com XML</PartnerName> <Code>test05091</Code> <OrderDate>2017-09-05T12:55:50+02:00</OrderDate> <Arrival>2017-09-11T00:00:00</Arrival> <Departure>2017-09-12T00:00:00</Departure> <CustomerFirstName>Michał1</CustomerFirstName> <CustomerName>Krasicki</CustomerName> <CustomerCountryCode>PL</CustomerCountryCode> <CustomerAddress>Witunia ul. Złotowska 14</CustomerAddress> <CustomerCity>Więcbork</CustomerCity> <CustomerZip /> <CustomerEmail>mail@mail.com</CustomerEmail> <CustomerPhone>503087111</CustomerPhone> <CustomerComments> Breakfast at 6 BED PREFERENCE:Double or Twin Room: 2 singles You have a booker that would like free parking. (based on availability) </CustomerComments> <ExtraInfo> rate_id: 918508, rewritten_from_id: 0, rewritten_from_name: Secret rate </ExtraInfo> <CommissionInfo /> <CancellationPolicy /> <ccType>VISA</ccType> <ccNumber>4111111111111111</ccNumber> <ccExpireDate>2020-08-01T00:00:00</ccExpireDate> <ccCVV>111</ccCVV> <ccHolderName>tes test</ccHolderName> <TotalPrice>209.53</TotalPrice> <Currency>USD</Currency> <PaymentType>Unspecified</PaymentType> <Status>Confirmed</Status> <LastStatusChanged>2017-09- 05T14:30:43+02:00</LastStatusChanged> <Rooms> <OrderRoom> <RoomId>45522</RoomId> <RatePlanId>39345</RatePlanId> <RoomCode>115945402</RoomCode> <RatePlanCode>7578970</RatePlanCode> <Name>Standard Double or Twin Room</Name> <NumRooms>1</NumRooms> <NumAdults>2</NumAdults> <NumChildren>0</NumChildren> <MealType>Breakfast</MealType> <GuestNames /> <Sequence>1</Sequence> <Prices> <OrderRoomPrice> <Date>2017-09- 11T00:00:00</Date> <Price>209.53</Price> </OrderRoomPrice> </Prices> <AddOns /> </OrderRoom> </Rooms> <AddOns /> <NumAdults xsi:nil="true" /> </Order> </Orders> </GetOrdersResult> </GetOrdersResponse> </Envelope>
The processes described below are carried out for each of the reservations contained in the Orders 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
- iduser
- tokenuser
that represent the tokenized card and that will be necessary for subsequent operations. As of version 1.2, tokenize is allowed even if cvc does not arrive. Please, ask us to enable this option
In cases where a card has already been previously tokenized and the iduser / tokenuser pair has been returned previously, only the iduser element will be added to the Order node, which will coincide with the one assigned and returned at the time of the first tokenization of that card.
Card data transformation
In the returned response, the card will appear masked, 411111 ****** 1111. 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; Order & gt; will be as follows:
<Order> ... <ccType>VISA</ccType> <ccNumber>411111******1111</ccNumber> <ccExpireDate>2020-08-01T00:00:00</ccExpireDate> <ccHolderName>tes test</ccHolderName> ... <iduser>99999999</iduser> <tokenuser>XxXxXxXxXxXxX</tokenuser> </Order>
In case of an error in the tokenization, the iduser / tokenuser elements will not appear and a ds_error_id element will be added
<Order> ... <ccType>VISA</ccType> <ccNumber>411111******1111</ccNumber> <ccExpireDate>2020-08-01T00:00:00</ccExpireDate> <ccHolderName>tes test</ccHolderName> ... <ds_error_id>9999</iduser> </Order>
It will also be informed within the Order node, in the event that there is card data, whether the card belongs to the B2B category; possible values 1/0
<Order> ... <NumAdults xsi:nil="true" /> <b2b>0</b2b> <iduser>99999999</iduser> <tokenuser> XxXxXxXxXxXxX </tokenuser> </Order>
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/yieldplanetThe type of request that it expects is a post with an 'xml' parameter with the following structure:
<root> <booking> <xml> <request> <user_name>vuestro usuario YieldPlanet</user_name> <password>vuestra password YieldPlanet</password> <hotel_id>id del Hotel</hotel_id> <status_changed_since>cambio de estado desde</ status_changed_since> </request> </xml> <url>URL YieldPlanet 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 YieldPlanet, an error message will be sent the same as the one currently returned by YieldPlanet, with the following consideration: if the error occurs in the call to PAYCOMET (credentials, format) or in the call from PAYCOMET to YiledPlanet (timeout, no response, etc) the ErrorId element is replaced by ErrorId-PAYTPV, indicating that there has been no connection establishment with YieldPlanet. Once that point is passed, if an error occurs, exactly what is returned by YieldPlanet (with ErrorId element) will be returned:
PAYCOMET error prior to calling YieldPlanet
<?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 signature. Please check your configuration</ErrorMsg> <ErrorId-PAYTPV>1123</ErrorId-PAYTPV> <TimeStamp>2017-09- 07T13:32:56.7964590+02:00</TimeStamp> </Status> </GetOrdersResult> </GetOrdersResponse> </soap:Body> </soap:Envelope>
Error returned by YieldPlanet
<?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 YieldPlanet that allow the complete process to be verified.