Testing your integration

After you've integrated the endpoints and the notifications (recommended), make sure that you:

Fully understand the documentation before testing (especially on live properties).
Are PCI compliant as you have access to PCI data from reservations.
Set up a test environment. You'll need a test property that you have access to via the Reservations API. For more information, see Testing with real or test properties.
For testing on live reservations, get consent from the properties you connect with via the Reservations API to test the APIs on their reservations. This will enable you to test all the endpoints.
Use a valid credit card or PayPal and opt for flexible cancellation when making test reservations. Make sure to cancel the test reservation before the free cancellation period ends to get a refund.

If you need your test properties to be changed to a specific payment method, reach out to the Connectivity Support team.

Limitations

The Payments Refundable API cannot be tested with a test reservation as it’s hard to reproduce a scenario that moves a VCC to the refundable state.
The Payments Chargeable API can be tested only on a non-refundable reservation.

Testing the APIs

To test your integration, you need a machine account with permissions to call the Payments API. You can create machine accounts using the connectivity portal. Also see Using the Basic authentication scheme.

Testing with real or test properties

To test the Payment Details API, use test properties.
To test the Payments Refundable API and the Payments Chargeable API, use real properties.

Getting payout details for reservation

Send the request:

GET https://payments-api.booking.com/connectivity-payments/reservations/{reservation-id}

Example response:

{
  "meta": {
    "ruid": "1"
  },
  "data": {
    "reservation_id": "4482006106",
    "property_id": "367104",
    "payout_type": "NET",
    "total_price_of_reservation": {
      "total_amount_paid": {
        "currency": "EUR",
        "value": "6877",
        "decimals": 2
      },
      "total_amount_to_collect_at_property": {
        "currency": "EUR",
        "value": "6",
        "decimals": 0
      }
    },
    "partner_payout": {
      "total_payout": {
        "currency": "EUR",
        "value": "5749",
        "decimals": 2
      },
      "commissionable_price": {
        "currency": "EUR",
        "value": "6877",
        "decimals": 2
      },
      "commissions_and_charges": {
        "currency": "EUR",
        "value": "1128",
        "decimals": 2
      }
    },
    "payout": {
      "bank_transfers": [],
      "virtual_credit_cards": [
        {
          "activation_date": "2024-10-09",
          "id": "7ca61d4e-c905-46eb-ae5e-b384416d6fbb",
          "current_balance": {
            "currency": "EUR",
            "value": "0",
            "decimals": 0
          },
          "expiration_date": "2025-10-10",
          "status": "FULLY_CHARGED",
          "card_details": {
            "cvc": "737",
            "card_name": "Booking.com",
            "card_number": "12345678998765432",
            "card_expiry": "03/30"
          }
        }
      ]
    },
    "price_breakdown": [
      {
        "room_reservation_id": "5214001415",
        "charges": [
          {
            "type": "VAT",
            "amount": {
              "currency": "EUR",
              "value": "389",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "TRUE"
          },
          {
            "type": "City tax",
            "amount": {
              "currency": "EUR",
              "value": "6",
              "decimals": 0
            },
            "is_already_collected_from_guest": "FALSE",
            "is_included_total_partner_payout": "FALSE"
          },
          {
            "type": "COMMISSION",
            "amount": {
              "currency": "EUR",
              "value": "1032",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "FALSE"
          }
        ]
      }
    ]
  },
  "errors": [],
  "warnings": []
}

Getting price breakdown for reservation

Send the request:

GET https://payments-api.booking.com/connectivity-payments/reservations/{reservation-id}/breakdown

Example response:

{
  "meta": {
    "ruid": "1"
  },
  "data": {
    "reservation_id": "4482006106",
    "property_id": "367104",
    "payout_type": "NET",
    "total_price_of_reservation": {
      "total_amount_paid": {
        "currency": "EUR",
        "value": "6877",
        "decimals": 2
      },
      "total_amount_to_collect_at_property": {
        "currency": "EUR",
        "value": "6",
        "decimals": 0
      }
    },
    "partner_payout": {
      "total_payout": {
        "currency": "EUR",
        "value": "5749",
        "decimals": 2
      },
      "commissionable_price": {
        "currency": "EUR",
        "value": "6877",
        "decimals": 2
      },
      "commissions_and_charges": {
        "currency": "EUR",
        "value": "1128",
        "decimals": 2
      }
    },
    "price_breakdown": [
      {
        "room_reservation_id": "5214001415",
        "charges": [
          {
            "type": "VAT",
            "amount": {
              "currency": "EUR",
              "value": "389",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "TRUE"
          },
          {
            "type": "City tax",
            "amount": {
              "currency": "EUR",
              "value": "6",
              "decimals": 0
            },
            "is_already_collected_from_guest": "FALSE",
            "is_included_total_partner_payout": "FALSE"
          },
          {
            "type": "COMMISSION",
            "amount": {
              "currency": "EUR",
              "value": "1032",
              "decimals": 2
            },
            "is_already_collected_from_guest": "TRUE",
            "is_included_total_partner_payout": "FALSE"
          }
        ]
      }
    ]
  },
  "errors": [],
  "warnings": []
}

Getting BT payout details for reservation

Send the request:

GET https://payments-api.booking.com/connectivity-payments/reservations/{reservation-id}/payout/bt

Example response:

{
  "meta": {
    "ruid": "2"
  },
  "data": {
    "reservation_id": "4482006106",
    "property_id": "367104",
    "payout_type": "NET",
    "payout": {
      "bank_transfers": [
        {
          "amount": {
            "currency": "EUR",
            "value": "5749",
            "decimals": 2
          },
          "status": "PENDING",
          "payout_date": "2024-11-28"
        }
      ]
    }
  },
  "errors": [],
  "warnings": []
}

Getting VCC payout details for reservation

Send the request:

GET https://payments-api.booking.com/connectivity-payments/reservations/{reservation-id}/payout/vcc?vcc-id={vcc-id}

Example response:

{
  "meta": {
    "ruid": "2"
  },
  "data": {
    "reservation_id": "4349189723",
    "property_id": "246631",
    "payout_type": "GROSS",
    "payout": {
      "virtual_credit_cards": [
        {
          "activation_date": "2024-10-09",
          "id": "7ca61d4e-c905-46eb-ae5e-b384416d6fbb",
          "current_balance": {
            "currency": "EUR",
            "value": "0",
            "decimals": 0
          },
          "expiration_date": "2025-10-10",
          "status": "FULLY_CHARGED",
          "card_details": {
            "cvc": "737",
            "card_name": "Booking.com",
            "card_number": "1234567891234567",
            "card_expiry": "03/30"
          }
        }
      ]
    }
  },
  "errors": [],
  "warnings": []
}

Getting details on refundable VCCs

Send the request:

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

Example response:

{
  "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": []
}

Getting details on chargeable VCCs

Send the request:

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

Example response:

{
  "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": []
}

Testing the notifications

If you've integrated the notifications (recommended), below you can find example notification messages.

`PAYOUT_UPDATE`

Example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "PAYOUT_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264
    }
}

`VIRTUAL_CREDIT_CARD_UPDATE`

Example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "VIRTUAL_CREDIT_CARD_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264,
        "vccId": "FC70575E-ED0E-11EE-B5FA-B675273SHDDBC"
    }
}

`PAYOUT_METHOD_UPDATE`

Example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "PAYOUT_METHOD_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264
    }
}

`BANK_TRANSFER_UPDATE`

Example:

{
    "metadata": {
        "uuid": "FC70575E-ED0E-11EE-B5FA-B675273ACEB0",
        "type": "BANK_TRANSFER_UPDATE",
        "payloadVersion": "1.0"
    },
    "payload": {
        "timestamp": "2023-12-10T10:01:322Z",
        "propertyId": 10345,
        "reservationId": 432647264
    }
}