|
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 a few days prior to the reservation Arrival Date
or 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. If the guest verifies this
is the card for the authorization, the cardId value found in the get
reservation response is used in the request for authorization to indicate
use of existing credit card payment method.
|
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": "<ID_NUMBER>",
"type": "Profile"
}
],
"profile": {
"customer": {
"personName": [
{
"givenName": "FirstName",
"surname": "LastName",
"nameType": "Primary"
},
{
"givenName": "FirstName",
"surname": "LastName",
"nameType": "Alternate"
},
{
"nameType": "External"
}
],
"gender": "Unknown",
"birthDate": "<DATE_OF_BIRTH",
"nationality": "CA",
"nationalityDescription": "<NATIONALITY>"
},
"addresses": {
"addressInfo": [
{
"address": {
"isValidated": true,
"addressLine": [
"<ADDRESS>",
null,
null,
null
],
"postalCode": "XXXXX",
"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": "<ID_NUMBER>",
"type": "Email"
},
{
"email": {
"emailAddress": "username@example.com
",
"type": "EMAIL",
"primaryInd": false
},
"id": "<ID_NUMBER>",
"type": "Email"
}
]
},
"profileType": "Guest"
}
},
"arrivalTransport": {
"transportationReqd": false
},
"departureTransport": {
"transportationReqd": false
},
"primary": true
}
],
"reservationPaymentMethods": [
{
"paymentCard": {
"cardId": {
"id": "<ID_NUMBER>",
"type": "CreditCard"
},
"cardType": "Va",
"cardNumberMasked": "XXXXXXXXXXXXXXXX",
"expirationDateMasked": "XX/XX",
"expirationDateExpired": false,
"cardHolderName": "FirstName LastName",
"processing": "Eft",
"swiped": false,
"cardPresent": false,
"cardOrToken": "Token"
},
"emailFolioInfo": {
"email": {
"emailAddress": "username@example.com
"
},
"emailFolio": false,
"id": "<ID_NUMBER>",
"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
|
Partner can
make an additional call to get 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 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 credit card 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 for the VISA credit card. The last 4 digits
of 1007 will be used for the authorization.
|
getPaymentMethods
{{HostName}}/rsv/v1/hotels/{{HotelId}}/reservations/{{ReservationId}}/paymentMethods?includeAmounts=true
200 Response
{
"reservationPaymentMethods":[
{
"paymentCard":{
"cardId":{
"id":"<ID_NUMBER>",
"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 hotel’s 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 1 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 reservation
information and the guest's verification to use the existing credit
card payment method on the reservation, 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 be the cardId
to indicate the existing credit card payment method on the reservation
is to be used for the authorization and the terminalId (can be retrieved
from step 3). Although there is no expectation to interact with a
device, it is good practice to always populate the terminalId in the
requests.
The data that
is sent to the PSP for the authorization is pulled from the reservation.
The cardId is used to get the token, and the cardtype and the amount
to be authorized is retrieved from the authorization
rule on the reservation.
You
can specify an amount that is 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"
},
A successful response
from the PSP will include the approval code and the amount authorized.
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 authorize amount on credit card ( Declined for no funds )",
"detail": "Failed to authorize amount on credit card ( Declined for no funds )",
"o:errorCode": "FOF00226",
"instance": "instance-XXXXXXX",
"language": "en"
}
|
postAuthorizeCreditCardAmount
{{HostName}}/csh/v1/hotels/{{HotelId}}/reservations/{{ReservationId}}/paymentMethods/creditCard/authorize
Simplest Request Body:
{
"criteria": {
"payment": {
"paymentCard": {
"cardId": {
"id": "874911",
"type": "CreditCard"
}
},
"folioView": "1"
},
"terminalId": "KIOSKREADER",
"evaluateApprovalAmount": true,
"sourceOfAuthorization": "CheckIn",
"updateReservation": true
}
}
201 Response:
{
"payment": {
"authorizationApproval": {
"approvalAmount": {
"amount": 230
},
"approvalCode": "A1235 ",
"originalAuthSequence": XXXXXXX
}
}
}
|
