Scenario 4: Guest has New Card for Settlement

Figure 6-4 Sequence Diagram for Scenario 4


This image shows the sequence diagram for scenario 4 where guest has a new card for settlement:.

Table 6-4 Description of Steps

Description of Steps Operation Samples

1

Partner queries the guest reservation to retrieve the reservation payment method and inform the guest that a payment can be made on the credit card during the stay (to reduce the charges existing on the reservation folio) or it is time to checkout (to pay for the reservation charges).

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 would like to use a different credit card for the settlement of the reservation charges and are present at the property.

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": "<FIRST_NAME>",
                                            "surname": "<LAST_NAME>",
                                            "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": "874911",
                                "type": "CreditCard"
                            },
                            "cardType": "Va",
                            "cardNumberMasked": "XXXXXXXXXXXXXXXX",
                            "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": "<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

The Partner can use the get Folios call to fetch the amounts that are outstanding on the reservation and inform the guests of their reservation charges and the amount that will be posted to their credit card.

A reservation can have multiple folios open with charges on each. The payment method can also be specific to the folio window. The get Folios response provides this data.

The roomStay balance amount is the full amount balance on the reservation. 

The reservationsFolioWindows section provides the balance amount for the individual folio window number and the payment method set for that folio. Each folio window with a balance amount must be settled individually.

The guests indicate they would like to use a different credit card for the settlement of the reservation charges and are present at the property.

getFolios

{{HostName}}/csh/v1/hotels/{{HotelId}}/reservations/{{ReservationId}}/folios?guestPayOnly=true&includeFolioHistory=false&groupType=CheckNo&fetchInstructions=Windowbalances&fetchInstructions=Reservation&fetchInstructions=Payment&fetchInstructions=Payee&simpleFolio=false&limit=100

200 Response:

{
    "reservationFolioInformation": {
        "reservationInfo": {
            "reservationIdList": [
                {
                    "id": "<ID_NUMBER>",
                    "type": "Reservation"
                },
                {
                    "id": "<ID_NUMBER>",
                    "type": "Confirmation"
                }
            ],
            "roomStay": {
                "arrivalDate": "2017-08-27",
                "departureDate": "2017-08-30",
                "originalTimeSpan": {
                    "startDate": "2017-08-27",
                    "endDate": "2017-08-30"
                },
                "bookingTimeSpan": {},
                "expectedTimes": {
                    "reservationExpectedArrivalTime": "2024-07-19 16:36:39.0",
                    "reservationExpectedDepartureTime": "2017-08-30"
                },
                "adultCount": 1,
                "childCount": 0,
                "roomClass": "ALL",
                "roomType": "ASTQ",
                "numberOfRooms": 1,
                "roomId": "501",
                "roomOwnershipType": "Regular",
                "ratePlanCode": "ANI",
                "rateAmount": {
                    "amount": 300,
                    "currencyCode": "USD"
                },
                "rateSuppressed": false,
                "fixedRate": false,
                "guarantee": {
                    "guaranteeCode": "CHECKED IN",
                    "shortDescription": "Checked In"
                },
                "marketCode": "ADH",
                "marketDescription": "AD HOC GROUPS",
                "sourceCode": "VOI",
                "sourceCodeDescription": "Call Center",
                "balance": {
                    "amount": 355.86,
                    "currencyCode": "USD"
                },
                "compBalance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "roomTypeCharged": "ASTQ",
                "roomNumberLocked": false,
                "pseudoRoom": false,
                "backToBackSequence": {},
                "backToBack": false
            },
            "reservationGuest": {
                "givenName": " <FIRST_NAME>",
                "surname": "<LAST_NAME>",
                "vip": {},
                "address": {
                    "country": {}
                },
                "anonymization": {},
                "accompanyGuests": [],
                "externalInfo": {},
                "guestRestricted": false,
                "nameType": "Guest",
                "id": "<ID_NUMBER>",
                "type": "Profile"
            },
            "sharedGuests": [],
            "attachedProfiles": [],
            "reservationPaymentMethod": {
                "paymentCard": {
                    "cardType": "Va"
                },
                "paymentMethod": "VA"
            },
            "reservationFolioWindows": [
                {
                    "payeeInfo": {
                        "payeeName": "<FULL_NAME>"
                    },
                    "balance": {
                        "amount": 345.86
                    },
                    "paymentMethod": "VA",
                    "folioWindowNo": 1
                },
                {
                    "payeeInfo": {
                        "payeeName": "<FULL_NAME>"
                    },
                    "balance": {
                        "amount": 10
                    },
                    "paymentMethod": "CA",
                    "folioWindowNo": 2
                }
            ],
            "reservationIndicators": [
                {
                    "indicatorName": "CALLHISTORY",
                    "count": 1
                },
                {
                    "indicatorName": "HISTORYFUTURE",
                    "count": 1
                },
                {
                    "indicatorName": "ASSOCIATEDPROFILES",
                    "count": 1
                },
                {
                    "indicatorName": "DAILYDETAILS",
                    "count": 0
                }
            ],
            "roomStatus": "Clean",
            "sourceOfSale": {
                "sourceType": "PMS",
                "sourceCode": "WEB"
            },
            "waitlist": {},
            "taxType": {
                "collectingAgentTax": false,
                "printAutoAdjust": false
            },
            "guestPreferredCurrency": "USD",
            "reservationCommunication": {
                "telephones": {},
                "emails": {}
            },
            "advanceCheckIn": {
                "advanceCheckedIn": false
            },
            "hotelId": "HotelId",
            "hotelName": "Executive Cloud Hotel",
            "roomStayReservation": true,
            "createDateTime": "2024-07-18 20:45:40.0",
            "lastModifyDateTime": "2024-07-19 17:06:41.0",
            "reservationStatus": "InHouse",
            "computedReservationStatus": "InHouse",
            "walkInIndicator": false,
            "commissionPayoutTo": "None",
            "paymentMethod": "VA",
            "preRegistered": false,
            "openFolio": false,
            "allowMobileCheckout": false,
            "optedForCommunication": false
        },
        "folioWindows": [
            {
                "revenue": {
                    "amount": 345.86,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 345.86,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "paymentMethod": {
                    "paymentCard": {
                        "cardId": {
                            "id": "<ID_NUMBER>",
                            "type": "CreditCard"
                        },
                        "cardType": "Va",
                        "cardNumberMasked": "XXXXXXXXXXXXXXXX",
                        "expirationDateMasked": "XX/XX",
                        "expirationDateExpired": false,
                        "processing": "Manual",
                        "swiped": true,
                        "cardPresent": false,
                        "cardOrToken": "Token"
                    },
                    "authorizationRule": {
                        "code": 2,
                        "amount": {
                            "amount": 25,
                            "currencyCode": "USD"
                        }
                    },
                    "paymentMethod": "VA",
                    "description": "<CREDITCARD_TYPE>",
                    "folioView": 1
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 1,
                "internalFolioWindowID": "1111111",
                "emptyFolio": false,
                "emptyWindow": false,
                "simpleFolio": false,
                "paymentsOnly": false
            },
            {
                "revenue": {
                    "amount": 10,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 10,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "paymentMethod": {
                    "paymentMethod": "CA",
                    "folioView": 2
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 2,
                "internalFolioWindowID": "1111111",
                "emptyFolio": false,
                "emptyWindow": false,
                "simpleFolio": false,
                "paymentsOnly": false
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 3,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": true
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 4,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": true
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 5,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": true
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 6,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": true
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 7,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": true
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 8,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": true
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 101,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": false
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 102,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": false
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 103,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": false
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 104,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": false
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 105,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": false
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitPayment": {
                    "currencyCode": "USD"
                },
                "debitBalance": {
                    "currencyCode": "USD"
                },
                "payeeInfo": {
                    "payeeId": {
                        "id": "<ID_NUMBER>",
                        "type": "Profile"
                    },
                    "payeeName": "<FULL_NAME>",
                    "payeeAddress": {
                        "address": {
                            "country": {}
                        }
                    }
                },
                "compAccountingInfo": {},
                "folioWindowNo": 106,
                "emptyFolio": true,
                "emptyWindow": true,
                "simpleFolio": false,
                "paymentsOnly": false
            },
            {
                "revenue": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "payment": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "balance": {
                    "amount": 0,
                    "currencyCode": "USD"
                },
                "debitP


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

When guests have verified the amount to charge and indicated they would like to use a different credit card for the payment and are present at the credit card reader device (Kiosk terminal), the postBillingPayments call can be made to process the credit card settlement request.

With the terminalId for use and the guest prepared to dip/tap/swipe their credit card, the Partner can initiate the request that will go out to the Payment Service Povider through OPI. The post BillingPayments API will trigger the credit card settlement request to be sent out to the PSP for processing.

The request body of the post Billing Payments requires a cardType, and paymentMethod (CP can be used generically), the terminalId the PSP will activate for the guest to dip/swipe their card (can be retrieved from step 3), and the amount to be applied to the credit card. 

If there was existing authorization up to the amount asked for on the reservation's credit card, a settlement request is processed with that existing approval code.

If there was not an authorization or not enough authorization for the asked for amount, an automatic authorization (or top-up) will be processed first and then the settlement request will be processed.

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

It is expected that the PSP will activate the device "KIOSKREADER" for an authorization/settlement request and prompt the guest to dip/tap/swipe their credit card.

A successful response from the PSP is returned with the amount, payment type, and transaction information. The payment is saved to the guest's reservation folio and the folio balance will be reduced by that amount.

The new credit card used for the settlement will not overwrite the existing payment method on the reservation.

If the settlement is declined, the message from the PSP (if provided) for the decline reason will be included in the response. 

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

postBillingPayments

{{HostName}}/csh/v1/hotels/{{HotelId}}/reservations/{{ReservationId}}/payments

Request Body:

{
    "criteria": {
        "paymentMethod": {
            "paymentCard": {
                "cardType": "Mc"
            },
            "paymentMethod": "MC",
            "folioView": "1"
        },
        "postingAmount": {
            "amount": "345.86",
            "currencyCode": "USD"
        },
        "terminalId": "KIOSKREADER",
        "applyCCSurcharge": false,
        "overrideInsufficientCC": false,
        "overrideARCreditLimit": false,
        "vATOffset": false,
        "action": "Billing",
        "cashierId": "{{CashierId}}",
        "folioWindowNo": "1",
        "postingReference": "cardid test"
    }
}


201 Response:

{
    "postings": [
        {
            "reference": "cardid test",
            "postedAmount": {
                "amount": 345.86,
                "currencyCode": "USD"
            },
            "price": {
                "amount": 345.86,
                "currencyCode": "USD"
            },
            "quantity": 1,
            "transactionType": "Payment",
            "creditAmount": {
                "amount": 345.86,
                "currencyCode": "USD"
            },
            "cashierInfo": {
                "cashierId": 140,
                "cashierName": "Test Cashier"
            },
            "paidOut": false,
            "exchange": {
                "creditAmount": {
                    "amount": 345.86,
                    "currencyCode": "USD"
                }
            },
            "stampDuty": false,
            "customCharge": false,
            "transactionNo": 1111111111,
            "transactionDate": "2017-08-27",
            "transactionCode": "XXXXX",
            "transactionAmount": 345.86,
            "postingDate": "2017-08-27",
            "postingTime": {
                "time": "2024-07-19 22:32:59.0",
                "timezone": "UTC"
            },
            "revenueDate": "2017-08-27",
            "receiptNo": 8,
            "roundingDifferenceTrx": false,
            "folioWindowNo": 1,
            "deferredTax": false
        }
    ],
    "trxCodesInfo": [
        {
            "description": "Mastercard",
            "transactionGroup": "PAY",
            "transactionSubGroup": "CCARD",
            "trxServiceType": "S",
            "transactionCode": "XXXXX",
            "hotelId": "HotelId",
            "printTrxReceipt": false
        }
    ]
}