# 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](#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
API Definition
`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-9353af0a4f4f",
  "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
API Definition
#### 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"
    }
  }
}
```