Virtual credit card (VCC) payments

Overview

A Virtual Credit Card (VCC) is a secure payment method offered by booking channels such as Booking.com and Expedia Connect. Instead of giving you the guest’s personal card details, the channel collects payment from the guest and provides you with a VCC to charge for the reservation.

This guide covers how to work with VCCs from Expedia and Booking.com in Guesty.

Identify the payment method type

Step 1: Extract the guest and reservation IDs

Retrieve the reservation using the legacy GET /reservations or GET /reservations-v3

Request example

curl --location --request GET 'https://open-api.guesty.com/v1/reservations/6a38e141065949001399c741?fields=_id%20confirmationCode%20status%20integration.platform%20checkInDateLocalized%20checkOutDateLocalized%20source%20stay%20guestId%20guest%20listingId%20listing.nickname%20listing.title%20listing.timezone%20listing.address.full%20listing.type%20money.payments.paymentMethodId%20createdAt%20confirmedAt' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {token}'

curl --location --globoff --request GET 'https://open-api.guesty.com/v1/reservations-v3?reservationIds[]={reservationId}&includePaymentsTemplate=true&mergeAccommodationFarePriceComponents=false' \
--header 'accept: application/json' \
--header 'authorization: Bearer {token}'

Locate and cache the guest._id/guestId (legacy) or bookerId (v3) and the reservation _id

Response example (extract with shapes maintained)

{
  "_id": "reservationIdString",
  "integration": {
    "platform": "expedia",
    "_id": "integrationIdString",
    "limitations": {
      "availableStatuses": []
    }
  },
  "confirmationCode": "EXP-string",
  "status": "confirmed",
  "source": "Expedia",
  "listingId": "listingIdString",
  "confirmedAt": "2026-06-22T07:16:17.804Z",
  "guest": {
    "_id": "guestIdString",
    "firstName": "Given name",
    "lastName": "Surname",
    "fullName": "Full name",
    "email": "Primary email"
  },
  "money": {
    "currency": "USD",
    "payments": [
      {
        "paymentMethodId": "paymentMethodIdString"
      }
    ]
  },
  "checkInDateLocalized": "2026-06-22",
  "checkOutDateLocalized": "2026-06-29",
  "accountId": "accountIdString",
  "guestId": "guestIdString",
  "createdAt": "2026-06-22T07:16:18.334Z",
  "stay": [],
  "listing": {
    "_id": "listingIdString",
    "type": "MTL_CHILD",
    "address": {
      "full": "6 Ave, New York, NY 10038, United States"
    },
    "nickname": "Listing nickname",
    "title": "Listing title",
    "timezone": "America/New_York"
  }
}

[
  {
    "_id": "reservationIdString",
    "createdAt": "2026-06-22T07:16:18.334Z",
    "bookingDate": "2026-06-22T07:16:18.334Z",
    "status": "confirmed",
    "confirmationCode": "EXP-string",
    "accountId": "accountIdString",
    "checkInDateLocalized": "2026-06-22",
    "checkOutDateLocalized": "2026-06-29",
    "conversationId": "conversationIdString",
    "source": "Expedia",
    "platform": "expedia",
    "bookerId": "aka the guest ID string",
    "integrationId": "integrationIdString",
    "guestsCount": 2,
    "numberOfGuests": {},
    "legacySystem": true,
    "systemSource": "LEGACY",
    "unitTypeId": "multi-unit ID/single listing ID",
    "unitId": "sub-unit ID/single listing ID",
    "eta": "2026-06-22T16:00:00.000Z",
    "etd": "2026-06-29T11:00:00.000Z",
    "stay": [
      {
        "checkInDateLocalized": "2026-06-22",
        "checkOutDateLocalized": "2026-06-29",
        "guestsCount": 2,
        "numberOfGuests": {
          "numberOfAdults": 2,
          "numberOfInfants": 0,
          "numberOfChildren": 0,
          "numberOfPets": 0
        },
        "unitTypeId": "multi-unit ID/single listing ID",
        "unitId": "sub-unit ID/single listing ID",
        "eta": "2026-06-22T16:00:00.000Z",
        "etd": "2026-06-29T11:00:00.000Z",
        "earlyCheckIn": {
          "blockDay": false
        },
        "lateCheckOut": {
          "blockDay": false
        }
      }
    ],
    "customFields": [],
    "confirmedAt": "2026-06-22T07:16:17.804Z",
    "alteredAt": "2026-06-22T07:16:54.110Z",
    "guestStay": {},
    "manuallyCreated": false,
    "conversationExternalId": "Expedia conversation ID",
    "channelMetadata": {},
    "ratePlans": [],
    "isUsingVCC": true,
    "money": {}
  }
]

Step 2: Retrieve the payment method object

Using the guest and reservation ID, retrieve the guest payment method object

curl --location --request GET 'https://open-api.guesty.com/v1/guests/{guestId}/payment-methods?reservationId={reservationId}' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {token}'

Locate the type property and note its value.VIRTUAL indicates that the reservation is being paid for with a VCC while PHYSICAL means a regular credit card

[
    {
        "_id": "paymentMethodId",
        "accountId": "accountId",
        "guestId": "guestId",
        "paymentProviderId": "paymentProviderId",
        "method": "AMARYLLIS",
        "payload": {
            "id": "payloadId",
            "billing_details": {
                "address": {
                    "line1": "NA",
                    "state": "NA",
                    "country": "NA",
                    "city": "NA",
                    "postal_code": "NA"
                }
            },
            "tokenId": "paymentTokenId"
        },
        "saveForFutureUse": true,
        "reuse": false,
        "createdAt": "2026-06-22T08:19:42.716Z",
        "status": "PENDING_ACTIVATION",
        "type": "VIRTUAL",
        "confirmationCode": "EXP-string",
        "activationDate": "2026-06-25T21:00:00.000Z",
        "updatedAt": "2026-06-22T08:19:42.716Z",
        "__v": 0
    }
]

🚧
Legacy VCC property
Both the legacy and v3 reservation payloads may include the parameter isUsingVCC. It is a legacy property that may not carry forward into future versions and should not be relied upon for payment method type identification.

How to work with VCCs

You can only charge a VCC during its activation window, which is set by the booking channel. Make sure to charge the card only after the activation date and before the expiration date, and only for the amount loaded onto the card. VCCs are not valid for authorization holds. If you try to charge outside these limits, the payment will fail or return an "Invalid card" error.

To save time and avoid missed payments, set up payment automations in your Guesty dashboard to automatically charge the VCC on or after its activation date. If you prefer to charge manually, wait at least 24 hours after check-in before processing the payment.

What can be charged to a VCC?

You can only collect the exact amount loaded onto the VCC by the booking channel. Guesty will charge this amount and wait until the activation date before processing the payment.

Modification limitations

The booking channel sets the VCC terms and conditions. If a guest changes their stay dates, the VCC activation date may stay the same unless the channel updates it. Follow the steps below to manage VCC payments for modified reservations.

Contact the booking channel to request updated payment details if needed. Let them know you have not received a new activation date for the VCC.
Create a new payment method using the billing details you collected and link it to the reservation
Cancel any existing payment automations on the reservation
Schedule new payments with the new payment method, or post payments manually when it is time to collect them

Overview

Identify the payment method type

Step 1: Extract the guest and reservation IDs

Step 2: Retrieve the payment method object

How to work with VCCs

What can be charged to a VCC?

Modification limitations

Further reading