|
1
|
Partner queries the guest reservation to retrieve the reservation
payment method and inform the guest that a credit card
pre-authorization can be completed. This can be done at the time
the guest is ready for check-in.
The get reservation response includes the payment method on the
reservation and the last 4 digits of the credit card. The guest
is informed that a credit card settlement is requested on the
VISA card’s last 4 digits of 1007.
The guests indicate they are at the hotel and would like to use a
different credit card for the reservation.
|
getReservation
{{HostName}}/rsv/v1/hotels/{{HotelId}}/reservations/{{ReservationId}}?fetchInstructions=Reservation&fetchInstructions=ReservationPaymentMethods
200 Response with reservationPaymentMethods>paymentMethod=VA (VISA) and paymentCard>cardId>id:
{
"reservations": {
"reservation": [
{
"reservationIdList": [
{
"id": "<ID_NUMBER>",
"type": "Reservation"
},
{
"id": "<ID_NUMBER>",
"type": "Confirmation"
}
],
"sourceOfSale": {
"sourceType": "PMS",
"sourceCode": "HOTEL"
},
"roomStay": {
"registrationNumber": {
"id": "",
"type": "Reservation"
},
"currentRoomInfo": {
"roomType": "STDQ",
"roomOwnershipType": "Regular"
},
"roomRates": [
{
"total": {
"amountBeforeTax": 200
},
"rates": {
"rate": [
{
"base": {
"amountBeforeTax": 200,
"baseAmount": 200
},
"shareDistributionInstruction": "Full",
"total": {
"amountBeforeTax": 0
},
"start": "2024-09-11",
"end": "2024-09-11"
}
]
},
"guestCounts": {
"childBuckets": {
"bucket1Count": 0,
"bucket2Count": 0,
"bucket3Count": 0,
"bucket4Count": 0,
"bucket5Count": 0
},
"adults": 2,
"children": 0
},
"roomType": "STDQ",
"ratePlanCode": "IHUBASE1",
"start": "2024-09-11",
"end": "2024-09-11",
"suppressRate": false,
"marketCode": "CORP",
"marketCodeDescription": "Group Corporate (SUBH)",
"sourceCode": "CAT",
"sourceCodeDescription": "Catering",
"numberOfUnits": 1,
"pseudoRoom": false,
"roomTypeCharged": "STDQ",
"houseUseOnly": false,
"complimentary": false,
"fixedRate": false,
"discountAllowed": true,
"bogoDiscount": false,
"allowAutoCheckIn": false
}
],
"arrivalDate": "2024-09-11",
"departureDate": "2024-09-12",
"expectedTimes": {
"reservationExpectedArrivalTime": "2024-09-11",
"reservationExpectedDepartureTime": "2024-09-12"
},
"guarantee": {
"guaranteeCode": "6PM",
"shortDescription": "6pm Hold"
},
"total": {
"amountBeforeTax": 0
},
"totalPoints": {
"points": 0
},
"roomNumberLocked": false,
"printRate": true
},
"reservationGuests": [
{
"profileInfo": {
"profileIdList": [
{
"id": "1099873",
"type": "Profile"
}
],
"profile": {
"customer": {
"personName": [
{
"givenName": "<FIRST_NAME>",
"surname": "<LAST_NAME>",
"nameType": "Primary"
},
{
"givenName": "<FIRST_NAME>",
"surname": "<LAST_NAME>",
"nameType": "Alternate"
},
{
"nameType": "External"
}
],
"gender": "Unknown",
"birthDate": "1985-01-02",
"nationality": "CA",
"nationalityDescription": "<NATIONALITY>"
},
"addresses": {
"addressInfo": [
{
"address": {
"isValidated": true,
"addressLine": [
"<ADDRESS>",
null,
null,
null
],
"postalCode": "<POSTAL_CODE>",
"country": {
"value": "United States of America",
"code": "USA",
"displayCountryFlag": true
},
"language": "ES",
"type": "HOMES",
"primaryInd": true
},
"id": "<ID_NUMBER>",
"type": "Address"
}
]
},
"emails": {
"emailInfo": [
{
"email": {
"emailAddress": "username@example.com",
"type": "EMAIL",
"primaryInd": true
},
"id": "885779",
"type": "Email"
},
{
"email": {
"emailAddress": "username@example.com",
"type": "EMAIL",
"primaryInd": false
},
"id": "1847216",
"type": "Email"
}
]
},
"profileType": "Guest"
}
},
"arrivalTransport": {
"transportationReqd": false
},
"departureTransport": {
"transportationReqd": false
},
"primary": true
}
],
"reservationPaymentMethods": [
{
"paymentCard": {
"cardId": {
"id": "874911",
"type": "CreditCard"
},
"cardType": "Va",
"cardNumberMasked": "XXXXXXXXXXXX1007",
"expirationDateMasked": "XX/XX",
"expirationDateExpired": false,
"cardHolderName": "<FULL_NAME>,
"processing": "Eft",
"swiped": false,
"cardPresent": false,
"cardOrToken": "Token"
},
"emailFolioInfo": {
"email": {
"emailAddress": "username@example.com"
},
"emailFolio": false,
"id": "885779",
"type": "Email"
},
"paymentMethod": "VA",
"description": "<CREDITCARD_TYPE>",
"folioView": 1
}
],
"cashiering": {
"billingPrivileges": {
"postingRestriction": false,
"preStayCharging": true,
"postStayCharging": false,
"videoCheckout": true,
"creditLimitAutoPay": true
},
"reverseCheckInAllowed": false,
"reverseAdvanceCheckInAllowed": false,
"transactionsPosted": false
},
"extSystemSync": true,
"hotelId": "{{HotelId}}",
"roomStayReservation": true,
"reservationStatus": "Reserved",
"computedReservationStatus": "Reserved",
"walkIn": false,
"printRate": true,
"createDateTime": "2024-02-28 22:23:18.0",
"creatorId": "FIRST_TEST@TEST_ENT1",
"lastModifyDateTime": "2024-02-28 22:23:18.0",
"lastModifierId": "FIRST_TEST@TEST_ENT1",
"createBusinessDate": "2024-02-29",
"preRegistered": false,
"upgradeEligible": false,
"allowAutoCheckin": false,
"hasOpenFolio": false,
"allowMobileCheckout": true,
"allowMobileViewFolio": false,
"allowPreRegistration": false,
"optedForCommunication": false,
"chargeCardNumber": "XXXXXXXXX",
"backToBack": false,
"payeeSharer": false
}
]
},
"masterInfoList": [
{
"codeInfo": [
{
"description": "United States of America",
"code": "USA"
}
],
"codeType": "Country"
},
{
"codeType": "State"
},
{
"codeInfo": [
{
"description": "Home Address",
"code": "HOMES"
}
],
"codeType": "AddressType"
}
],
"links": [... ]
}
|
|
2
|
The Partner can make an additional call to get the reservation
payment methods to obtain more information for the reservation
payment methods. The response will have the authorizationRule
with the amount the site asks for authorizing on the
reservation, the approvalAmountNeeded with the amount that is
still needed for authorization, and the currentAuthorizedAmount
with the amount, if any, of an existing authorization. If
approvalAmountNeeded is 0 amount, it is expected that no
creditcard authorization is needed.
With the get reservation call and this get reservation payment
methods call, the guest can be provided information that a $230
authorization is needed and their VISA credit card with last 4
digits of 1007 will be used for the authorization.
Again, in this scenario, the guests have indicated that they are
at the hotel for Check-in and would like to use a different
credit card for the reservation authorization. They are at the
Kiosk station and prepared to dip/tap/swipe their credit
card.
|
getPaymentMethods
{{HostName}}/rsv/v1/hotels/{{HotelId}}/reservations/{{ReservationId}}/paymentMethods?includeAmounts=true
200 Response
{
"reservationPaymentMethods":[
{
"paymentCard":{
"cardId":{
"id":"874911",
"type":"CreditCard"
},
"currentAuthorizedAmount":{
"amount":0,
"currencyCode":"USD"
},
"approvalAmountNeeded":{
"amount":230,
"currencyCode":"USD"
},
"cardType":"Va",
"cardNumberMasked":"xxxx",
"expirationDateMasked":"XX/XX",
"expirationDateExpired":false,
"processing":"Eft",
"swiped":false,
"cardPresent":false,
"cardOrToken":"Token"
},
"balance":{
"amount":0,
"currencyCode":"USD"
},
"authorizationRule":{
"code":5,
"amount":{
"amount":230,
"currencyCode":"USD"
}
},
"paymentMethod":"VA",
"description":"<CREDITCARD_TYPE>",
"folioView":1
}
],
"links":[ ]
}
|
|
3
|
The configured credit card reader devices must be known to send
with the authorization and settlement requests. A kiosk system
might have the credit card reader device attached and it is
known. Others will need to fetch the hotels configured external
devices to get the id of a configured device to populate the
terminalId element in the authorization and settlement APIs. The
label is expected to be descriptive to indicate where that
reader exists. The deviceArea can also be used to identify an
area where more than one reader device can belong.
This configuration does not change often, and it is recommended
to cache the result and refresh only if issues occur around the
credit card reader devices.
|
getConfiguredExternalDevices
{{HostName}}/int/config/v1/configuredExternalDevices?deviceType=CreditCard&
active=true&
hotelId={{HotelId}}
&deviceCode=ChipAndPin
200 Response:
{
"configuredExternalDevices": {
"deviceType": "CreditCard",
"supportedExternalDevices": [
{
"hotelId": "{{HotelId}}",
"supportedDevices": [
{
"deviceType": "CreditCard",
"deviceCode": "ChipAndPin",
"deviceArea": "FRONTOFFICE",
"displayName": "Chip and Pin Terminal/Device",
"mobileYN": false,
"desktopYN": false,
"active": true,
"id": "1CCREADER1",
"label": "Lobby East",
"translatableLabel": {
"defaultText": "Lobby East",
"translatedTexts": []
},
"iDEditable": true
},
{
"deviceType": "CreditCard",
"deviceCode": "ChipAndPin",
"deviceArea": "FRONTOFFICE",
"displayName": "Chip and Pin Terminal/Device",
"mobileYN": false,
"desktopYN": false,
"active": true,
"id": "2CCREADER2",
"label": "Lobby West",
"translatableLabel": {
"defaultText": "Lobby West",
"translatedTexts": []
},
"iDEditable": true
},
{
"deviceType": "CreditCard",
"deviceCode": "ChipAndPin",
"deviceArea": "BACKOFFICE",
"displayName": "Chip and Pin Terminal/Device",
"mobileYN": false,
"desktopYN": false,
"active": true,
"id": "3CCREADER3",
"label": "Back Office Accounting",
"translatableLabel": {
"defaultText": "Back Office Accounting",
"translatedTexts": []
},
"iDEditable": true
},
{
"deviceType": "CreditCard",
"deviceCode": "ChipAndPin",
"deviceArea": "FRONTOFFICE",
"displayName": "Chip and Pin Terminal/Device",
"mobileYN": false,
"desktopYN": false,
"active": true,
"id": "KIOSKREADER",
"label": "Kiosk 1 Reader",
"translatableLabel": {
"defaultText": "Kiosk 1 Reader",
"translatedTexts": []
},
"iDEditable": true
},
{
"deviceType": "CreditCard",
"deviceCode": "ChipAndPin",
"displayName": "Chip and Pin Terminal/Device",
"mobileYN": false,
"desktopYN": false,
"active": true,
"id": "5CCREADER5",
"label": "FD Center",
"translatableLabel": {
"defaultText": "FD Center",
"translatedTexts": []
},
"iDEditable": true
}
]
}
]
},
"links": []
}
|
|
4
|
With the terminalId and the guest prepared to dip/tap/swipe their
credit card, the Partner can initiate an authorization request
that will go out to the Payment Service Provider through OPI.
The post AuthorizeCreditCardAmount API will trigger the credit
card authorization request to be sent out to the PSP for
approval. The minimum elements needed in the request body would
the cardType and paymentMethod (CP can be used generically), and
the terminalId the PSP will activate for the guest to dip/swipe
their card (can be retrieved from step 3).
The authorization request will not have any token/card number
provided, which indicates to the PSP that a device will need to
be activated to capture the credit card from the
guest.
The amount to be authorized is populated automatically in the
request to PSP as it is retrieved from the authorization rule on
the reservation.
You can specify an amount that can be sent in the post
AuthorizeCreditCardAmount request body that will be used if
needed. This section can be added in the "criteria" for
it:
"amount": {
"amount": "500",
"currencyCode": "USD"
},
It is expected that the PSP will activate the device
"KIOSKREADER" for an authorization request and prompt the guest
to dip/tap/swipe their credit card.
A successful response from the PSP will include the approval
code, the new cardId>id, the cardType, paymentMethod, and the
amount authorized.
The new card type, expiration date, token, and last 4 digits will
be saved to the guest's reservation (overwriting the previous
payment method).
If the authorization is declined, the message from the PSP (if
provided) for the decline reason will be included.
Sample 400 Response:
{
"type": "Bad Request",
"title": "Failed to settle amount on credit card ( Decline no process )",
"detail": "Failed to settle amount on credit card ( Decline no process )",
"o:errorCode": "FOF00227",
"instance": "instance-XXXXXXX",
"language": "en"
}
|
postAuthorizeCreditCardAmount
{{HostName}}/csh/v1/hotels/{{HotelId}}/reservations/{{ReservationId}}/paymentMethods/creditCard/authorize
Simplest Request Body:
{
"criteria": {
"payment": {
"paymentCard": {
"cardType": "Va"
},
"paymentMethod": "VI",
"folioView": "1"
},
"terminalId": "KIOSKREADER",
"evaluateApprovalAmount": false,
"sourceOfAuthorization": "CheckIn",
"updateReservation": true
}
}
201 Response:
{
"payment": {
"paymentCard": {
"cardId": {
"id": "1002416",
"type": "CreditCard"
},
"cardType": "Mc",
"cardNumberMasked": "",
"expirationDate": "2028-07-01"
},
"paymentMethod": "MC",
"authorizationApproval": {
"approvalAmount": {
"amount": 230
},
"approvalCode": "A1241 ",
"originalAuthSequence": 1833670
}
}
}
|
