Managing chargeable VCCs

The Payments Chargeable API provides information on chargeable VCCs at property level with the frequency you require. Querying this API is useful in situations where the partner needs to know if they have some funds left on their VCCs that they can still charge.

Getting details on chargeable VCCs

GET https://payments-api.booking.com/connectivity-payments/properties/{property-id}/chargeable-vccs

The GET /connectivity-payments/properties/{property-id}/chargeable-vccs request enables you to get information on chargeable VCCs associated with a given accommodation property.

Getting VCC details

For security reasons, when querying this endpoint, you get a list of chargeable VCCs IDs but not the VCC details required to make a charge. If you don't already have the details of the given VCCs in your system, such as the VCC number, its CVC, or expiry date, you need to query the /reservations/{reservation-id}/payout/vcc?vcc-id={vcc-id} endpoint.

Recommended frequency

The recommended frequency for calling the API is once in 12 hours (per property), with pagination.

Persisting response data

As you don't receive notifications about changes to chargeable VCCs and when calling the respective endpoint, you only get a list of chargeable VCC IDs (and not the VCC details), the Payments Chargeable API is not suited for persistence. This means that you should not store the response data in your system as it may lead to issues and data mismatch.

For example, if a VCC is no longer chargeable, its ID won't be returned as a result of calling the endpoint. However, if you persisted the response data from when the given VCC was still chargeable, your system will still show it as such, even when it's no longer in the chargeable state.

Path parameters

The following table describes what elements you must add as path parameters:

Element	Description	Type	Required/Optional
`property-id`	Specifies the identifier of the property.	string	required

Query parameters

The following table describes what elements you must add as query parameters:

Element	Description	Type	Required/Optional
`page`	Specifies the page number for a paginated response. See Pagination below. The page size must be greater or equal to `1`.	integer	required
`page-size`	Specifies the number of entries to be included on one page for a paginated response. The page size must be between `1` and `100`. See Pagination below.	integer	required

Pagination

Paginate results by specifying page and page-size. For example, these two requests return the first 100 results, on two pages of 50 results each:

1. GET /connectivity-payments/properties/{property-id}/chargeable-vccs?page=1&page-size=50

2. GET /connectivity-payments/properties/{property-id}/chargeable-vccs?page=2&page-size=50

To check the total number of entries and whether a next page exists, look for the total_count and next_page parameters in the response:

"meta": {
        "total_count": 100,
        "next_page": true
    }

Response body example

The following is a successful response body example:

{
  "meta": {
    "ruid": "1",
    "total_count": 12,
    "next_page": true
  },
  "data": [
    {
      "reservation_id": "4050539948",
      "current_balance": {
        "currency": "EUR",
        "value": "18955",
        "decimals": 2
      },
      "vcc_id": "001c035b-e150-41cf-9db3-311784f50f93",
      "vcc_status": "FUNDED"
    },
    {
      "reservation_id": "4938651150",
      "current_balance": {
        "currency": "EUR",
        "value": "6052",
        "decimals": 1
      },
      "vcc_id": "20b633bd-a01a-4828-8963-39190851c494",
      "vcc_status": "FUNDED"
    },
    {
      "reservation_id": "4644741843",
      "current_balance": {
        "currency": "EUR",
        "value": "10965",
        "decimals": 2
      },
      "vcc_id": "d769973f-612c-435e-b2c1-065c568f229e",
      "vcc_status": "FUNDED"
    },
    {
      "reservation_id": "4405455507",
      "current_balance": {
        "currency": "EUR",
        "value": "3912",
        "decimals": 0
      },
      "vcc_id": "bedc6c4e-6233-4bee-ac6b-020c866287bd",
      "vcc_status": "FUNDED"
    },
    {
      "reservation_id": "4758752719",
      "current_balance": {
        "currency": "EUR",
        "value": "352",
        "decimals": 0
      },
      "vcc_id": "d4e60277-bb46-4d48-80cc-e02cdbdfba14",
      "vcc_status": "FUNDED"
    },
    {
      "reservation_id": "4795611274",
      "current_balance": {
        "currency": "EUR",
        "value": "1991",
        "decimals": 0
      },
      "vcc_id": "87c67aed-7a35-4977-9d59-576702fec312",
      "vcc_status": "FUNDED"
    },
    {
      "reservation_id": "4906250005",
      "current_balance": {
        "currency": "EUR",
        "value": "2332",
        "decimals": 0
      },
      "vcc_id": "be8b1669-1f86-47a6-a9bb-32db39882768",
      "vcc_status": "FUNDED"
    },
    {
      "reservation_id": "4973445583",
      "current_balance": {
        "currency": "EUR",
        "value": "1358",
        "decimals": 0
      },
      "vcc_id": "7f0a1922-15ea-4e7e-aa61-962d1c892766",
      "vcc_status": "FUNDED"
    },
    {
      "reservation_id": "4545729875",
      "current_balance": {
        "currency": "EUR",
        "value": "666",
        "decimals": 0
      },
      "vcc_id": "6a9a88b4-a005-4c42-addc-8318a05decf1",
      "vcc_status": "FUNDED"
    },
    {
      "reservation_id": "4530535396",
      "current_balance": {
        "currency": "EUR",
        "value": "510",
        "decimals": 0
      },
      "vcc_id": "e9a1eee5-845b-440c-86fc-a20b58c01faf",
      "vcc_status": "FUNDED"
    }
  ],
  "errors": [],
  "warnings": []
}

Response body elements

The following table describes the response elements:

Element	Description	Type
`meta`	Contains the metadata about the paginated response.	object
: `total_count`	Specifies the total number of pages.	integer
: `next_page`	Specifies if a next page exists.	boolean
`data`	Contains the response data.	object
: `reservation_id`	Specifies the identifier of the reservation.	string
: `current_balance`	Contains information on the current balance of the given VCC.	object
:: `value`	Amount on the balance.	string
:: `currency`	Currency of the amount.	string
:: `decimals`	Number of decimals in the amount.	string
: `vcc_id`	Specifies the identifier of the given VCC.	string
:: `status`	Specifies the status of the VCC: `NOT_LOADED`, `FUNDED`, `CANCELLED`, `AVAILABLE`, `FULLY_CHARGED`, `PARTIALLY_CHARGED`, or `UNKNOWN`. For a description of the statuses, see VCC statuses.	string
`errors`	Contains potential errors. These can help you understand what went wrong with your request. For more information, see Response codes.	array
`warnings`	Contains potential warnings. These can help you improve your requests.	array

Response codes

This table lists and describes the response codes that the Payment Details API can return.

Code	Type	Description
200	Success	Information on the chargeable VCCs per given property is fetched successfully.
400	Non-retryable failure	Request payload is invalid.
401	Non-retryable failure	You are not authorized to fetch the requested information.
429	Retryable error	You exceeded the rate limit.
500	Retryable failure	Request failed with an internal server error.