# Lodging Lodging merchants operating under travel-related MCCs can pass enhanced stay details alongside their transactions, including check-in and check-out dates. Sending this data helps optimize interchange rates across all major card networks and prevents downgrades to higher commercial standard rates. ### Requirements - Your business must operate under an [eligible MCC](https://docs.finix.com/guides/industry-considerations/lodging#eligible-mccs-for-lodging-data). - Transactions must be captured within two days. ### Eligible MCCs for Lodging Data | MCC | Description | | -------- | ------------------------------------- | | 3501–3999| Hotels and motel chains | | 7011 | Lodging - hotels, motels, and resorts| ## Lodging Data Fields The following fields are available under the `additional_lodging_data` object on both `Authorization` and `Transfer` resources. All fields are optional for lodging MCC transactions. | Field | Description | Data Type | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------- | | `additional_lodging_data` | Nested object containing all lodging-specific fields. Returns `null` for non-lodging MCCs. | Object | | `check_in_date` | The guest's scheduled arrival date. | Object | | `check_out_date` | The guest's scheduled departure date. Must represent a date on or after `check_in_date`. | Object | | `customer_service_phone` | The phone number guests can call for support or inquiries related to their stay. | String | | `extra_charge_details` | Additional charges billed beyond the room rate. Each field represents a specific charge type, in cents. | Object | | `extra_charge_details.restaurant_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.mini_bar_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.laundry_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.other_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.phone_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.gift_shop_amount` | The amount of the additional charge, in cents. | Integer | | `hotel_agreement_number` | The folio or agreement number associated with the reservation. Max 12 characters; longer values are truncated. | String | | `is_advance_deposit` | Indicates whether the lodging charge is an advance deposit. | Boolean | | `is_no_show` | Set to `true` if the cardholder is being billed for a reserved room that was not occupied. | Boolean | | `number_of_nights` | The total number of nights for the lodging stay. | Integer | | `property_phone` | The direct phone number of the lodging property. | String | | `room_rate` | The nightly room rate, in cents. | String | | `room_tax` | The tax amount applied to the room rate, in cents. | String | ## Lodging Transaction Flow using the API Once you have a buyer `Identity` and `Payment Instrument`, include the `additional_lodging_data` object in your request to pass stay details. ### Create an Authorization with Lodging Data Include the `additional_lodging_data` object in the request body to pass stay details at authorization time: - Example ```bash post /authorizations ``` - Sandbox server https://finix.sandbox-payments-api.com/authorizations - cURL ```bash curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/authorizations \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "additional_lodging_data": { "check_in_date": { "month": 4, "day": 1, "year": 2026 }, "check_out_date": { "month": 4, "day": 5, "year": 2026 }, "customer_service_phone": "8005551234", "extra_charge_details": { "mini_bar_amount": 500 }, "hotel_agreement_number": "HTL98765", "is_advance_deposit": false, "is_no_show": false, "number_of_nights": 4, "property_phone": "4155559876", "room_rate": "10000", "room_tax": "1500" }, "amount": 45000, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PIkxmtueemLD6dN9ZoWGHT44", "tags": { "order_number": "HOTEL-2026-001" } }' ``` `additional_lodging_data` is **not** required at capture time (`PUT /authorizations/{id}`). The lodging data is automatically inherited from the original `Authorization`. #### Authorization Response ```json { "id": "AUwv72KC1ZG2BKS9zCoVgSG4", "created_at": "2026-06-25T23:08:50.93Z", "updated_at": "2026-06-25T23:08:50.93Z", "amount": 45000, "amount_requested": 45000, "currency": "USD", "state": "SUCCEEDED", "failure_code": null, "failure_message": null, "additional_lodging_data": { "check_in_date": { "month": 4, "day": 1, "year": 2026 }, "check_out_date": { "month": 4, "day": 5, "year": 2026 }, "customer_service_phone": "8005551234", "extra_charge_details": { "mini_bar_amount": 500 }, "hotel_agreement_number": "HTL98765", "is_advance_deposit": false, "is_no_show": false, "number_of_nights": 4, "property_phone": "4155559876", "room_rate": "10000", "room_tax": "1500" }, "additional_purchase_data": null, "additional_healthcare_data": null, "additional_motor_vehicle_rental_data": null, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "expires_at": "2026-07-02T23:08:50.93Z", "is_void": false, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "network_details": { "brand": "VISA", "authorization_code": "664979" }, "source": "PIkxmtueemLD6dN9ZoWGHT44", "tags": { "order_number": "HOTEL-2026-001" }, "trace_id": "7354286f-b769-491e-9e4e-9353af0a4f4", "transfer": null, "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUwv72KC1ZG2BKS9zCoVgSG4" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" } } } ``` ### Create a Transfer with Lodging Data Visa cards qualify for lower interchange rates only when using the authorization and capture flow. If you submit a `Transfer` (e.g. Sale) with Visa, the transaction will not receive the reduced interchange rate. The same `additional_lodging_data` object is supported on direct `Transfer` creation: - Example ```bash post /transfers ``` - Sandbox server https://finix.sandbox-payments-api.com/transfers - cURL ```bash curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/transfers \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "additional_lodging_data": { "check_in_date": { "month": 4, "day": 1, "year": 2026 }, "check_out_date": { "month": 4, "day": 5, "year": 2026 }, "customer_service_phone": "8005551234", "extra_charge_details": { "mini_bar_amount": 500 }, "hotel_agreement_number": "HTL98765", "is_advance_deposit": false, "is_no_show": false, "number_of_nights": 4, "property_phone": "4155559876", "room_rate": "10000", "room_tax": "1500" }, "amount": 45000, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PIkxmtueemLD6dN9ZoWGHT44" }' ``` #### Transfer Response ```json { "id": "TRtxRnYL2jveAWBSPrKZPJ15", "created_at": "2026-06-25T23:09:09.28Z", "updated_at": "2026-06-25T23:09:09.28Z", "amount": 45000, "amount_requested": 45000, "currency": "USD", "state": "SUCCEEDED", "type": "DEBIT", "failure_code": null, "failure_message": null, "additional_lodging_data": { "check_in_date": { "month": 4, "day": 1, "year": 2026 }, "check_out_date": { "month": 4, "day": 5, "year": 2026 }, "customer_service_phone": "8005551234", "extra_charge_details": { "mini_bar_amount": 500 }, "hotel_agreement_number": "HTL98765", "is_advance_deposit": false, "is_no_show": false, "number_of_nights": 4, "property_phone": "4155559876", "room_rate": "10000", "room_tax": "1500" }, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "network_details": { "brand": "VISA", "authorization_code": "999048", "acquirer_reference_number": null }, "operation_key": "CARD_NOT_PRESENT_SALE", "ready_to_settle_at": "2026-06-26T23:09:09.28Z", "source": "PIkxmtueemLD6dN9ZoWGHT44", "statement_descriptor": "FLX*FINIX FLOWERS", "tags": { "order_number": "HOTEL-2026-001" }, "trace_id": "05efc73f-8ad4-47d7-8bd3-e67a3b0fdafe", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtxRnYL2jveAWBSPrKZPJ15" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtxRnYL2jveAWBSPrKZPJ15/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtxRnYL2jveAWBSPrKZPJ15/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRtxRnYL2jveAWBSPrKZPJ15" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtxRnYL2jveAWBSPrKZPJ15/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkxmtueemLD6dN9ZoWGHT44" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ```