Lodging
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

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

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

{
  "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:

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

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

LodgingCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code