GuestyPay Tokenization Flow

Overview

There are two primary steps to creating a guest payment method through GuestyPay for reservations.

1. Collect and tokenize the guest's credit card.
2. Pass the token in the reservation creation request.

Step 1: Tokenize the Guest's Card

📘

Determine the Payment Processor ID

The API will automatically identify a property's payment processor when you include the listingId in your tokenization request. Even then, it is a best practice to include the paymentProviderId as well. You can retrieve it with the following request.

• Get payment provider by listing id

Payment Form and SDK

The quickest, easiest, and recommended way to facilitate payments on your website is by using our payment form SDK. Guesty offers a JavaScript SDK that supports multiple payment methods, ensuring that your guests enjoy a personalized and hassle-free checkout process. It's secure and PCI-compliant. You can access it at the links below.

• GitHub Wiki
• NPM package

Please note that the SDK only supports the GuestyPay.

Resources

❗️

Directly Interfacing with the API

Interfacing with the API directly, using the resources outlined below, should only be attempted if the SDK cannot be adapted for your use case. Even then, please contact Customer Experience and we will assist you with it. We plan to offer the SDK as the only method in the near future.

Available Endpoints

Payload

Card Object

This table describes the parameters of the card object from the Payload table above.

Billing Details Object

These are the parameters of the billing_details object from the Payload table above.

threeDS Object

Guesty offers two parameters that can help guide the user toward the next step in your booking process after an authentication attempt.

1. successURL is the next step in your booking flow after a successful authentication attempt. For example, post the token as the guest's payment method and send the user a booking confirmation message.

2. failureURL is the next step in your process after authentication fails. Your website/application should redirect the guest to the relevant page to either try again, provide an alternate payment method, or follow any other process you have in place for invalid credit cards.

3. 
   

🚧

Success and Failure URLs

If you don't provide any URLs, the user will be redirected to a blank white page after attempting to authenticate. To avoid this, we suggest specifying the URL of the next step in your booking process, based on the authentication result, for a better user experience.

Merchant Data

Example

Request

curl --location 'https://pay.guesty.com/api/tokenize/v2' \
--header 'Content-Type: application/json' \
--data '{  
    "listingId": "64f03f9094d741004fda977d",
    "card": {
        "number": "4580458045804580",
        "exp_month": "12",
        "exp_year": "2024",
        "cvc": "123"
    },
    "billing_details": {
        "name": "John Smith",
        "address": {
            "line1": "20 W 34th St",
            "city": "New York",
            "postal_code": "10001",
            "country": "US"
        }
    },
     "threeDS": {
        "amount": 500,
        "currency": "USD",
        "successURL": "https://book.pms.com?{orderN}",
        "failureURL": "https://book.pms.com/fail?{orderN}"
    },
     "merchantData": {
        "freeText": "PayeeId-1234567",
        "transactionDate": "2023-11-14T12:12:33.162Z",
        "transactionDescription": "Descriptor",
        "transactionId": "Reservation-2000583"
    }
}

 

Response

Send the authURL to the user to authenticate the payment method. Once the authentication process is complete, the user is redirected to either the successURL or failureURL specified in the tokenization request, depending on the outcome.

If authentication is successful no authURL is returned in the response (the issuer didn't require it), you may proceed to use the token_id to create the guest payment method.

Response

{
    "_id": "64d4d01f1884841581a7768e",
    "threeDS": {
        "authURL": "https://api.checkout.com/sessions-interceptor/sid_.....",
    }
}

Step 2: Create the Reservation

Pass the GuestyPay token you've generated as the ccToken in the Create inquiry for reservation based on quote or Create instant reservation based on quote requests.

Reuse of Tokens

Using the same payment token for multiple reservations is not supported. It will result in a missing payment method error in the user dashboard (even though it exists), preventing auto payments from being executed as scheduled. Generate a new token for each new inquiry or reservation through the Booking Engine API.

Troubleshooting