Managing refundable VCCs

The Payments Refundable API provides information on refundable VCCs at property level with the frequency you require. Querying this API is useful in situations where the partner needs to know to which VCCs they need to refund money to.

Getting details on refundable VCCs

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

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

Recommended frequency

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

Persisting response data

As you don't receive notifications about changes to refundable VCCs and when calling the respective endpoint, you only get a list of refundable VCC IDs (and not the VCC details), the Payments Refundable 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 refundable, 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 refundable, your system will still show it as such, even when it's no longer in the refundable state.

Path parameters

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

Query parameters

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

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}/refundable-vccs?page=1&page-size=50

2. GET /connectivity-payments/properties/{property-id}/refundable-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": "2",
    "total_count": 4,
    "next_page": false
  },
  "data": [
    {
      "reservation_id": "4245116985",
      "refund_status": "REFUNDABLE",
      "vcc_id": "9baca743-b7a3-4fad-bd68-5ae5428ba7ab",
      "refund_amount": {
        "currency": "USD",
        "value": "2689",
        "decimals": 1
      },
      "refund_due_date": "2023-12-31",
      "reason": "WAIVED_FEES",
      "comment": null
    },
    {
      "reservation_id": "3930438231",
      "refund_status": "REFUNDABLE",
      "vcc_id": "43404e10-4a7f-45c9-875d-3c31de3c4130",
      "refund_amount": {
        "currency": "USD",
        "value": "19356",
        "decimals": 2
      },
      "refund_due_date": "2024-06-30",
      "reason": "WAIVED_FEES",
      "comment": null
    },
    {
      "reservation_id": "4896421736",
      "refund_status": "REFUNDABLE",
      "vcc_id": "7d1b6db2-6760-4409-a20c-d6f1ba725f36",
      "refund_amount": {
        "currency": "USD",
        "value": "23248",
        "decimals": 2
      },
      "refund_due_date": "2024-10-31",
      "reason": "WAIVED_FEES",
      "comment": null
    },
    {
      "reservation_id": "4654216646",
      "refund_status": "REFUNDABLE",
      "vcc_id": "427d9676-7b11-4a54-93ee-3625bec4d2ba",
      "refund_amount": {
        "currency": "USD",
        "value": "13547",
        "decimals": 2
      },
      "refund_due_date": "2024-11-30",
      "reason": "WAIVED_FEES",
      "comment": null
    }
  ],
  "errors": [],
  "warnings": []
}	

Response body elements

The following table describes the response elements:

Response codes

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