{ "openapi": "3.0.1", "info": { "title": "Payments API", "description": "Retrieve payment and payout details for accommodation reservations, including partner payout information, breakdowns, bank transfer details, and VCC management.", "contact": { "name": "Connectivity Team", "url": "https://connect.booking.com", "email": "connectivity@booking.com" }, "version": "1.0" }, "servers": [ { "url": "https://payments-api.booking.com/", "description": "Test using live endpoint" } ], "tags": [ { "name": "About Try it", "description": "Learn how to effectively use the Try it feature in the Payments API documentation.\n\nUse the **Try it** feature to send test request examples to the API endpoints directly from the developer portal and depending on the selected environment either see static, pre-built responses or dynamic responses from a test property.\n\n## Environment\n\nYou can select between two different environments (top right corner in the UI):\n\n**Test static response** (default):\n- Helps to understand the response data schema\n- Recommended for all write operations (POST, PUT, DELETE)\n- Environment for testing without affecting live/test data\n\n**Test live endpoint**:\n- Make sure to use only test properties.\n- Changes will affect your test property data\n- Requires valid credentials\n- Same API structure as production\n\n## Request\n\nUsing the UI, toggle between **Edit** and **Preview** tabs to see the values applied to the path or query placeholders (if there are any). You can also click on any unresolved placeholders to add a value or edit an existing placeholder value.\n\nThe portal loads the default request body. Where the specification supports multiple request body examples (for example: Rooms API POST endpoint), you can choose a different request body from the drop-down list.\n\nSome helpful pointers before running a request:\n\n- **Authentication** (when using live endpoint): Configure your authentication headers\n - API Key or OAuth token as required. Use the **Environments** tab.\n - Make sure to manage separate machine accounts for test vs. properties in production.\n - Ensure credentials match your selected environment.\n\n- **Parameters**: Fill in required parameters\n - Path parameters (like `reservation-id`)\n\n- **Execute**: Click **Send** to send the request\n - The request is sent to the selected environment\n - When sending requests to the live endpoint, the response will be a real response from the API.\n\n## Response\n\nAfter executing a request, you will see:\n\n- **Status code**: HTTP response status\n- **Response body**: JSON response data\n- **Headers**: Response headers\n\n## Common issues\n\n- **401 Unauthorized**: Check your credentials\n- **403 Forbidden**: Verify access permissions\n- **404 Not Found**: Confirm the reservation ID exists\n- **410 Gone**: The checkout date is older than the allowed 18-months window" }, { "name": "Reservation payout details", "description": "Retrieve detailed partner payout information for accommodation reservations." }, { "name": "Reservation breakdown", "description": "Retrieve detailed breakdown for accommodation reservations with respect to partner payout." }, { "name": "Bank transfer payout", "description": "Retrieve Bank Transfer payout details for accommodation reservations." }, { "name": "VCC payout details, per accommodation reservation", "description": "Provides VCC payout details for an accommodation reservation" }, { "name": "VCCs to be charged", "description": "Provides information of the VCCs to be charged." }, { "name": "Refundable VCCs", "description": "Provides information of the refundable VCCs." }, { "name": "Reservation Status API", "description": "Provides reservation status information with respect to a reservation ID." } ], "x-tagGroups": [ { "name": "API Endpoints", "tags": [ "Reservation payout details", "Reservation breakdown", "Bank transfer payout", "VCC payout details, per accommodation reservation", "VCCs to be charged", "Refundable VCCs", "Reservation Status API" ] }, { "name": "Documentation", "tags": [ "About Try it" ] } ], "paths": { "/connectivity-payments/reservations/{reservation-id}": { "get": { "tags": [ "Reservation payout details" ], "summary": "Get payout details for a reservation", "description": "Retrieve payout details for a reservation, including the estimated amount to be collected at the property, payout status and amount, commissions and charges, VCC or bank transfer payout details, and price breakdown.", "operationId": "getPayoutDetails", "parameters": [ { "name": "reservation-id", "in": "path", "description": "The unique identifier of the reservation.", "required": true, "schema": { "type": "integer" } }, { "name": "accept-version", "in": "header", "description": "API version to use.", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer token for authentication.", "required": true, "schema": { "type": "string" }, "example": "Bearer " } ], "responses": { "200": { "description": "Successfully retrieved payout details including the estimated amount to be collected at the property, payout status and amount, commissions and charges, VCC or bank transfer payout details, and price breakdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutDetailsResponse" } } } }, "400": { "description": "Invalid request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidTokenResponse" } } } }, "403": { "description": "Access Denied!", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedRequestResponse" } } } }, "404": { "description": "The reservation data is not found at this moment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationDataNotFoundErrorResponse" } } } }, "410": { "description": "Reservation cannot be processed because the checkout date is older than the allowed 18-months window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDateTooOldErrorResponse" } } } }, "500": { "description": "The request failed with an internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } } } }, "/connectivity-payments/reservations/{reservation-id}/breakdown": { "get": { "tags": [ "Reservation breakdown" ], "summary": "Get price breakdown for a reservation", "description": "Retrieve a detailed price breakdown for a given reservation, including VAT, applicable taxes, and fees, per each room the guest booked.", "operationId": "getPriceBreakdown", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authentication.", "required": true, "schema": { "type": "string" }, "example": "Bearer " }, { "name": "reservation-id", "in": "path", "description": "The unique identifier of the reservation.", "required": true, "schema": { "type": "integer" } }, { "name": "accept-version", "in": "header", "description": "API version to use.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved a detailed price breakdown for the reservation, including VAT, applicable taxes, and fees, per each room the guest booked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccommodationReservationPayoutBreakdownResponse" } } } }, "400": { "description": "Invalid request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidTokenResponse" } } } }, "403": { "description": "Access Denied!", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedRequestResponse" } } } }, "404": { "description": "The reservation data is not found at this moment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationDataNotFoundErrorResponse" } } } }, "410": { "description": "Reservation cannot be processed because the checkout date is older than the allowed 18-months window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDateTooOldErrorResponse" } } } }, "500": { "description": "The request failed with an internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } } } }, "/connectivity-payments/reservations/{reservation-id}/payout/bt": { "get": { "tags": [ "Bank transfer payout" ], "summary": "Get bank transfer payout details for a reservation", "description": "Retrieve information on the bank transfer payout for a reservation and any changes to the payout.", "operationId": "getBTDetails", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authentication.", "required": true, "schema": { "type": "string" }, "example": "Bearer " }, { "name": "reservation-id", "in": "path", "description": "The unique identifier of the reservation.", "required": true, "schema": { "type": "integer" } }, { "name": "accept-version", "in": "header", "description": "API version to use.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully fetched information about the Bank Transfer payouts associated with respective accommodation reservation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccommodationReservationBTPayoutResponse" } } } }, "400": { "description": "Invalid request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidTokenResponse" } } } }, "403": { "description": "Access Denied!", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedRequestResponse" } } } }, "404": { "description": "The reservation data is not found at this moment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationDataNotFoundErrorResponse" } } } }, "410": { "description": "Reservation cannot be processed because the checkout date is older than the allowed 18-months window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDateTooOldErrorResponse" } } } }, "500": { "description": "The request failed with an internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } } } }, "/connectivity-payments/reservations/{reservation-id}/payout/vcc": { "get": { "tags": [ "VCC payout details, per accommodation reservation" ], "summary": "Get VCC payout details for a reservation", "description": "Retrieve information on the virtual credit cards associated with a reservation and changes to the VCC payout.", "operationId": "getVCCDetailsPerReservation", "parameters": [ { "name": "reservation-id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "vcc-id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "accept-version", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer token for authentication.", "example": "Bearer " } ], "responses": { "200": { "description": "Successfully retrieved information about the VCCs associated with respective accommodation reservation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VCCPayoutResponse" } } } }, "400": { "description": "Invalid request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidTokenResponse" } } } }, "403": { "description": "Access Denied!", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedRequestResponse" } } } }, "404": { "description": "The reservation data is not found at this moment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationDataNotFoundErrorResponse" } } } }, "410": { "description": "Reservation cannot be processed because the checkout date is older than the allowed 18-months window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDateTooOldErrorResponse" } } } }, "500": { "description": "The request failed with an internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } } } }, "/connectivity-payments/properties/{property-id}/chargeable-vccs": { "get": { "tags": [ "VCCs to be charged" ], "summary": "Get chargeable VCCs for a property", "description": "Retrieve information on chargeable VCCs associated with a given accommodation property.", "operationId": "getVCCtoChargeForProperty", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authentication.", "required": true, "schema": { "type": "string" }, "example": "Bearer " }, { "name": "property-id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page-size", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 10 } ], "responses": { "200": { "description": "Successfully retrieved chargeable VCCs for the accommodation property", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccommodationPropertyVCCToChargeResponse" } } } }, "400": { "description": "Invalid request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidTokenResponse" } } } }, "403": { "description": "Access Denied!", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedRequestResponse" } } } }, "500": { "description": "The request failed with an internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } } } }, "/connectivity-payments/properties/{property-id}/refundable-vccs": { "get": { "tags": [ "Refundable VCCs" ], "summary": "Get refundable VCCs for a property", "description": "Retrieve details on refundable VCCs associated with a given accommodation property.", "operationId": "getVCCRefundablesForProperty", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for authentication.", "required": true, "schema": { "type": "string" }, "example": "Bearer " }, { "name": "property-id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "page-size", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 10 } ], "responses": { "200": { "description": "Successfully retrieved refundable VCCs for the accommodation property", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccommodationVCCRefundResponse" } } } }, "400": { "description": "Invalid request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidTokenResponse" } } } }, "403": { "description": "Access Denied!", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedRequestResponse" } } } }, "500": { "description": "The request failed with an internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } } } }, "/connectivity-payments/reservations/{reservation-id}/status": { "get": { "tags": [ "Reservation Status API" ], "summary": "Get reservation status", "description": "Provides status information for an accommodation reservation.", "operationId": "getReservationStatusResponse", "parameters": [ { "name": "reservation-id", "in": "path", "description": "The unique identifier of the reservation.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "Authorization", "in": "header", "description": "Bearer token for authentication.", "required": true, "schema": { "type": "string" }, "example": "Bearer " } ], "responses": { "200": { "description": "Successfully fetched information about the cc status associated with provided reservation id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationStatusResponse" } } } }, "400": { "description": "Invalid request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidTokenResponse" } } } }, "403": { "description": "Access Denied!", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedRequestResponse" } } } }, "410": { "description": "Reservation cannot be processed because the checkout date is older than the allowed 18-months window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDateTooOldErrorResponse" } } } }, "500": { "description": "The request failed with an internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } } } } }, "components": { "schemas": { "DefaultMeta": { "type": "object", "description": "Metadata for the response", "properties": { "ruid": { "type": "string", "description": "Request unique identifier", "example": "string" } } }, "Error": { "type": "object", "description": "Error response containing details about the error", "properties": { "description": { "type": "string", "description": "Description of the error" }, "message": { "type": "string", "description": "Error message" }, "status_code": { "type": "integer", "format": "int32", "description": "HTTP status code for the error" }, "debug_message": { "type": "string", "description": "Detailed debug message for the error" } } }, "Warning": { "type": "object", "description": "Warning information", "properties": { "message": { "type": "string", "description": "Warning message", "example": "string" } } }, "PaginationMeta": { "description": "Metadata for the response", "properties": { "ruid": { "type": "string" }, "total_count": { "type": "integer", "format": "int32", "description": "Total number of records." }, "next_page": { "type": "boolean", "description": "Next page exists" } }, "required": [ "ruid", "total_count", "next_page" ] }, "AmountPaid": { "description": "Contains information on the total amount the guest paid to Booking.com.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Amount paid by the guest." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "AmountToCollect": { "description": "Contains information on the estimated amount the partner needs to collect from the guest at checkin.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Estimated amount to be collected from the guest at checkin." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "AmountPayout": { "description": "Contains information on the total amount to be paid out to the partner.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total payout amount." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "AmountCommissionable": { "description": "Contains information on the total commissionable price.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total commissionable price." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "AmountCommissionsAndCharges": { "description": "Contains information on the total amount of commissions and other charges such as fees.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total amount of commissions and other charges." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "AmountCharges": { "description": "Contains information on the total amount of all charges.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total amount of all charges." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "AmountVCCBalance": { "description": "Contains information on the current balance of the VCC.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Current balance of the VCC." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "AmountRefund": { "description": "Contains information on the amount to be refunded.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Amount to be refunded." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "VCCCardDetails": { "type": "object", "description": "Card details for a virtual credit card", "properties": { "cvc": { "type": "string", "description": "Card verification code" }, "card_name": { "type": "string", "description": "Name on the card" }, "card_number": { "type": "string", "description": "Card number" }, "card_type": { "type": "string", "description": "Type of the VCC" }, "card_expiry": { "type": "string", "description": "Card expiry date (MM/YY)" } }, "required": [ "cvc", "card_name", "card_number", "card_expiry" ] }, "PayoutVCC": { "type": "object", "description": "Virtual credit card included in the payout", "properties": { "activation_date": { "type": "string", "format": "date", "description": "Date the VCC becomes active" }, "id": { "type": "string", "description": "VCC identifier" }, "current_balance": { "$ref": "#/components/schemas/AmountVCCBalance" }, "expiration_date": { "type": "string", "format": "date", "description": "Date the VCC expires" }, "status": { "type": "string", "description": "Possible VCC status values: NOT_LOADED, FUNDED, AVAILABLE, PARTIALLY_CHARGED, FULLY_CHARGED, CANCELLED, or UNKNOWN." }, "card_details": { "$ref": "#/components/schemas/VCCCardDetails" } }, "required": [ "id", "status", "current_balance", "card_details" ] }, "BTPayoutResponse": { "type": "object", "description": "Bank transfer payout data for a reservation", "properties": { "reservation_id": { "type": "string", "description": "Accommodation reservation identifier" }, "property_id": { "type": "string", "description": "Property identifier" }, "payout_type": { "type": "string", "description": "Type of payout: GROSS, NET, or UNKNOWN." }, "payout": { "type": "object", "description": "Payout instruments", "properties": { "bank_transfers": { "type": "array", "description": "Bank transfer payouts", "items": { "type": "object", "properties": { "amount": { "type": "object", "description": "Contains information on the amount to be transferred.", "properties": { "value": { "type": "string", "description": "Payout amount." }, "currency": { "type": "string", "description": "Currency of the amount." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "status": { "type": "string", "description": "Status of the bank transfer payout: PENDING, PAID, or UNKNOWN. While the status is PENDING, the estimated amount and payout_date are shown." }, "payout_date": { "type": "string", "description": "Date the amount is to be paid out to the partner. Format: YYYY-MM-DD." }, "bank_transfer_reference": { "type": "string", "description": "Identifier of the bank transfer payout." } } } } } } } }, "AccommodationReservationBTPayoutResponse": { "type": "object", "description": "Response having information of the Bank Transfer payouts associated with respective accommodation reservation", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "The meta" }, "data": { "allOf": [ { "$ref": "#/components/schemas/BTPayoutResponse" } ], "description": "The data" }, "errors": { "type": "array", "maxItems": 0, "items": {} }, "warnings": { "type": "array", "maxItems": 0, "items": {} } } }, "BreakdownResponse": { "type": "object", "description": "Detailed payout breakdown for a reservation", "properties": { "reservation_id": { "type": "string", "description": "Accommodation reservation identifier" }, "property_id": { "type": "string", "description": "Property identifier" }, "payout_type": { "type": "string", "description": "Type of payout: GROSS, NET, or UNKNOWN." }, "payment_tags": { "type": "array", "description": "Payment tags associated with the reservation.", "items": { "type": "string" } }, "total_price_of_reservation": { "type": "object", "description": "Breakdown of the total reservation price", "properties": { "total_amount_paid": { "$ref": "#/components/schemas/AmountPaid" }, "total_amount_to_collect_at_property": { "$ref": "#/components/schemas/AmountToCollect" } } }, "partner_payout": { "type": "object", "description": "Partner payout summary", "properties": { "total_payout": { "$ref": "#/components/schemas/AmountPayout" }, "commissionable_price": { "$ref": "#/components/schemas/AmountCommissionable" }, "commissions_and_charges": { "type": "object", "description": "Contains information on the total amount of commissions and other charges such as fees.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total amount of commissions and other charges." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." }, "breakdown": { "type": "object", "description": "Breakdown of commissions and charges.", "properties": { "total_commissions": { "type": "object", "description": "Total commission amount.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total commission amount." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "total_charges": { "type": "object", "description": "Total charges amount.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total charges amount." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } } } } } } } }, "price_breakdown": { "type": "array", "description": "Per-room price breakdown", "items": { "type": "object", "properties": { "room_reservation_id": { "type": "string", "description": "Room reservation identifier" }, "charges": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Charge type (e.g. Tax, COMMISSION)" }, "amount": { "$ref": "#/components/schemas/AmountCharges" }, "is_already_collected_from_guest": { "type": "string", "description": "If set to TRUE, the charged amount has already been collected from the guest and the partner does not need to collect anything. If set to FALSE, the partner has to collect the money at checkin. If set to UNKNOWN, no information is available." }, "is_included_total_partner_payout": { "type": "string", "description": "If set to TRUE, the charged amount is included in the payout and will be transferred to the partner. If set to FALSE, the charged amount is intended for another party, such as the government. If set to UNKNOWN, no information is available." }, "applicable_rate": { "type": "object", "nullable": true, "description": "The rate applied to calculate the charge.", "properties": { "type": { "type": "string", "description": "How the rate is applied (e.g. PERCENTAGE)." }, "value": { "type": "string", "description": "Rate value." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the rate value." } } }, "applicable_type": { "type": "array", "nullable": true, "description": "The type of applicable rate.", "items": { "type": "string" } } } } } } } } } }, "AccommodationReservationPayoutBreakdownResponse": { "type": "object", "description": "Response of partner payout information with detailed breakdown for respective accommodation reservation", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "The meta" }, "data": { "allOf": [ { "$ref": "#/components/schemas/BreakdownResponse" } ], "description": "The data" }, "errors": { "type": "array", "maxItems": 0, "items": {} }, "warnings": { "type": "array", "maxItems": 0, "items": {} } } }, "PayoutDetails": { "type": "object", "description": "Detailed payout information for a reservation", "properties": { "reservation_id": { "type": "string", "description": "Accommodation reservation identifier" }, "property_id": { "type": "string", "description": "Property identifier" }, "payout_type": { "type": "string", "description": "Type of payout: GROSS, NET, or UNKNOWN." }, "payout_status": { "type": "string", "description": "Status of the payout: PENDING, PAID, PARTIALLY_PAID, CANCELLED, or UNKNOWN." }, "payment_tags": { "type": "array", "description": "Payment tags associated with the reservation.", "items": { "type": "string" } }, "total_price_of_reservation": { "type": "object", "description": "Breakdown of the total reservation price", "properties": { "total_amount_paid": { "$ref": "#/components/schemas/AmountPaid" }, "total_amount_to_collect_at_property": { "$ref": "#/components/schemas/AmountToCollect" } } }, "partner_payout": { "type": "object", "description": "Partner payout summary", "properties": { "total_payout": { "$ref": "#/components/schemas/AmountPayout" }, "commissionable_price": { "$ref": "#/components/schemas/AmountCommissionable" }, "commissions_and_charges": { "type": "object", "description": "Contains information on the total amount of commissions and other charges such as fees.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total amount of commissions and other charges." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." }, "breakdown": { "type": "object", "description": "Breakdown of commissions and charges.", "properties": { "total_commissions": { "type": "object", "description": "Total commission amount.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total commission amount." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "total_charges": { "type": "object", "description": "Total charges amount.", "properties": { "currency": { "type": "string", "description": "Currency of the amount." }, "value": { "type": "string", "description": "Total charges amount." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } } } } } } } }, "payout": { "type": "object", "description": "Payout instruments", "properties": { "bank_transfers": { "type": "array", "description": "Bank transfer payouts", "items": { "type": "object", "properties": { "amount": { "type": "object", "description": "Contains information on the amount to be transferred.", "properties": { "value": { "type": "string", "description": "Payout amount." }, "currency": { "type": "string", "description": "Currency of the amount." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the amount." } } }, "status": { "type": "string", "description": "Status of the bank transfer payout: PENDING, PAID, or UNKNOWN." }, "payout_date": { "type": "string", "description": "Date the amount is to be paid out to the partner. Format: YYYY-MM-DD." }, "bank_transfer_reference": { "type": "string", "description": "Identifier of the bank transfer payout." } } } }, "virtual_credit_cards": { "type": "array", "description": "Virtual credit card payouts", "items": { "$ref": "#/components/schemas/PayoutVCC" } }, "customer_credit_cards": { "type": "array", "description": "Reserved for future Payments API updates.", "items": { "type": "object" } } } }, "price_breakdown": { "type": "array", "description": "Per-room price breakdown", "items": { "type": "object", "properties": { "room_reservation_id": { "type": "string", "description": "Room reservation identifier" }, "charges": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Charge type (e.g. Tax, COMMISSION)" }, "amount": { "$ref": "#/components/schemas/AmountCharges" }, "is_already_collected_from_guest": { "type": "string", "description": "If set to TRUE, the charged amount has already been collected from the guest and the partner does not need to collect anything. If set to FALSE, the partner has to collect the money at checkin. If set to UNKNOWN, no information is available." }, "is_included_total_partner_payout": { "type": "string", "description": "If set to TRUE, the charged amount is included in the payout and will be transferred to the partner. If set to FALSE, the charged amount is intended for another party, such as the government. If set to UNKNOWN, no information is available." }, "applicable_rate": { "type": "object", "nullable": true, "description": "The rate applied to calculate the charge.", "properties": { "type": { "type": "string", "description": "How the rate is applied (e.g. PERCENTAGE)." }, "value": { "type": "string", "description": "Rate value." }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimals in the rate value." } } }, "applicable_type": { "type": "array", "nullable": true, "description": "The type of applicable rate.", "items": { "type": "string" } } } } } } } } } }, "PayoutDetailsResponse": { "type": "object", "description": "Response containing detailed payout information for a reservation", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "Response metadata" }, "data": { "allOf": [ { "$ref": "#/components/schemas/PayoutDetails" } ], "description": "Payout details" }, "errors": { "type": "array", "maxItems": 0, "items": {} }, "warnings": { "type": "array", "maxItems": 0, "items": {} } } }, "VCCPayoutData": { "type": "object", "description": "VCC payout information for a reservation", "properties": { "reservation_id": { "type": "string", "description": "Accommodation reservation identifier" }, "property_id": { "type": "string", "description": "Property identifier" }, "payout_type": { "type": "string", "description": "Type of payout: GROSS, NET, or UNKNOWN." }, "payout": { "type": "object", "description": "Payout instruments", "properties": { "virtual_credit_cards": { "type": "array", "description": "Virtual credit card payouts", "items": { "$ref": "#/components/schemas/PayoutVCC" } } } } } }, "VCCPayoutResponse": { "type": "object", "description": "Response containing VCC payout information for a reservation", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "Response metadata" }, "data": { "allOf": [ { "$ref": "#/components/schemas/VCCPayoutData" } ], "description": "VCC payout data" }, "errors": { "type": "array", "maxItems": 0, "items": {} }, "warnings": { "type": "array", "maxItems": 0, "items": {} } } }, "ChargeableVCCInformation": { "description": "Information regarding VCC to be charged", "properties": { "reservation_id": { "type": "integer", "description": "Accommodation reservation identifier" }, "current_balance": { "$ref": "#/components/schemas/AmountVCCBalance" }, "vcc_id": { "type": "string", "description": "VCC identifier" }, "vcc_status": { "type": "string", "description": "VCC Status", "example": "ACTIVE" } } }, "AccommodationPropertyVCCToChargeResponse": { "description": "Response regarding VCCs to be charged per accommodation property", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "data": { "type": "array", "description": "Data containing required information", "items": { "$ref": "#/components/schemas/ChargeableVCCInformation" } }, "errors": { "type": "array", "maxItems": 0, "items": {} }, "warnings": { "type": "array", "maxItems": 0, "items": {} } } }, "VCCRefundInformation": { "description": "Information regarding refund associated with an accommodation reservation", "properties": { "reservation_id": { "type": "integer", "description": "Accommodation reservation identifier" }, "refund_status": { "type": "string", "description": "Refund status", "example": "REFUNDABLE" }, "vcc_id": { "type": "string", "description": "VCC identifier" }, "refund_amount": { "$ref": "#/components/schemas/AmountRefund" }, "refund_due_date": { "type": "string", "description": "Due date for the refund" }, "reason": { "type": "string", "description": "Reason for the refund" }, "comment": { "type": "string", "nullable": true, "description": "Additional comments for the refund" } } }, "AccommodationVCCRefundResponse": { "description": "Response having information regarding VCC refunds associated with an accommodation reservations", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "data": { "type": "array", "description": "Data containing required information", "items": { "$ref": "#/components/schemas/VCCRefundInformation" } }, "errors": { "type": "array", "maxItems": 0, "items": {} }, "warnings": { "type": "array", "maxItems": 0, "items": {} } } }, "InvalidTokenResponse": { "type": "object", "description": "Response when the authentication token is missing, invalid, or expired.", "properties": { "meta": { "$ref": "#/components/schemas/DefaultMeta" }, "warnings": { "type": "array", "description": "List of warnings for the response", "maxItems": 0, "items": {} }, "errors": { "type": "array", "description": "List of errors for the response", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "string", "nullable": true, "description": "Additional error details" } } } } } }, "UnauthorizedRequestResponse": { "type": "object", "description": "Response when the token is valid but does not have access to the requested resource.", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "The meta" }, "data": { "type": "object", "description": "Data containing required information" }, "errors": { "type": "array", "description": "List of errors for the response", "items": { "$ref": "#/components/schemas/Error" } }, "warnings": { "type": "array", "description": "List of warnings for the response", "items": { "$ref": "#/components/schemas/Warning" } } } }, "InternalServerErrorResponse": { "type": "object", "description": "Response when the request failed with an internal reason", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "The meta" }, "data": { "type": "object", "description": "Data containing required information" }, "errors": { "type": "array", "description": "List of errors for the response", "items": { "$ref": "#/components/schemas/Error" } }, "warnings": { "type": "array", "description": "List of warnings for the response", "items": { "$ref": "#/components/schemas/Warning" } } } }, "BadRequestErrorResponse": { "type": "object", "description": "Response when the request doesn't have valid parameters", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "The meta" }, "data": { "type": "object", "description": "Data containing required information" }, "errors": { "type": "array", "description": "List of errors for the response", "items": { "$ref": "#/components/schemas/Error" } }, "warnings": { "type": "array", "description": "List of warnings for the response", "items": { "$ref": "#/components/schemas/Warning" } } } }, "ReservationDataNotFoundErrorResponse": { "type": "object", "description": "Response when the reservation data is not found", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "The meta" }, "data": { "type": "object", "description": "Data containing required information" }, "errors": { "type": "array", "description": "List of errors for the response", "items": { "$ref": "#/components/schemas/Error" } }, "warnings": { "type": "array", "description": "List of warnings for the response", "items": { "$ref": "#/components/schemas/Warning" } } } }, "CheckoutDateTooOldErrorResponse": { "type": "object", "description": "Response when the checkout date is older than the allowed 18-months window", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "The meta" }, "data": { "type": "object", "description": "Data containing required information" }, "errors": { "type": "array", "description": "List of errors for the response", "items": { "$ref": "#/components/schemas/Error" } }, "warnings": { "type": "array", "description": "List of warnings for the response", "items": { "$ref": "#/components/schemas/Warning" } } } }, "ReservationStatusData": { "type": "object", "description": "Reservation status information", "properties": { "reservationId": { "type": "string", "description": "Accommodation reservation identifier" }, "payoutType": { "type": "string", "description": "Type of payout: GROSS, NET, or UNKNOWN." }, "propertyId": { "type": "string", "description": "Property identifier" } } }, "ReservationStatusResponse": { "type": "object", "description": "Response containing reservation status information", "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/DefaultMeta" } ], "description": "Response metadata" }, "data": { "allOf": [ { "$ref": "#/components/schemas/ReservationStatusData" } ], "description": "Reservation status data" }, "errors": { "type": "array", "maxItems": 0, "items": {} }, "warnings": { "type": "array", "maxItems": 0, "items": {} } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token for authentication. Use your API credentials to obtain a token." } } } }