Tokenizing Payment Methods

How to safely collect credit card details and store them as tokens for use with supported payment providers.

Overview

Guesty allows you to collect and store credit card details as tokens safely. This document explains how to tokenize the payment method for all supported payment processors. If you use Stripe, skip to the section at the bottom of this page to learn how to tokenize a payment method externally using Stripe.

To perform charges with the token, you must add a payment method to the guest using the add payment method API.

❗️

Important

To ensure seamless tokenization and payment processing, it's essential to integrate the appropriate payment processor with your Guesty account and listing.

Javascript SDK

Guesty offers a JavaScript SDK for supported payment methods, providing guests with a personalized and streamlined checkout experience on your page. It is secure and PCI-compliant. You can find the complete reference by clicking this link. If you're looking for the npm package, you can find it here. The SDK supports the GuestyPay, Merchant Warrior, and Hyp payment processors only.

Payment Capture Form

Payment Capture Form

📘

Declined Payment Method

In case the first payment method is declined on an existing reservation, you can add more payment methods (tokens) to the guest by using the add payment method API.

Understanding the API

Available Endpoints

MethodEndpoint
POSThttps://pay.guesty.com/api/tokenize/v2

Payload

Body ParameterData TypeDescriptionRequired
paymentProviderIdstringThe payment processing account ID as stored in Guesty - Learn more.✔️
cardobjectCredit card details.✔️
billing_detailsobjectBilling details.✔️
threeDSobject3D Secure validation (refer to the threeDS Object table below).✔️

Card Object

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

Body ParameterData TypeDescriptionRequired
numberstringCredit card number.✔️
exp_monthstringExpiration month in 2 digits string format ("04").✔️
exp_yearstringExpiration year in 4 digits string format ("2024").✔️
cvcstringCard verification code. Three digits in string format.✔️

Billing Details Object

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

Body ParameterData TypeDescriptionRequired
namestringCardholder name.✔️
addressobjectBilling address.✔️

Address Object

Here are the parameters of the address object from the billing_details object in the previous section above.

Body ParameterData TypeDescriptionRequired
citystringCity. Max length 50 characters.✔️
countrystringCountry. Max length 50 characters.✔️
line1stringStreet name and number Max length 50 characters.✔️
postal_codestringPostal code. Max length 20 characters.✔️

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 provide the user with 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.

Body ParameterData TypeDescriptionRequired
amountnumberThe total amount of the future payment.✔️
currencystringThe currency code. E.g. "USD"✔️
successURLstringURL for redirect after successful authentication.
failureURLstringURL for redirect after a failed authentication.

🚧

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.


Request example

curl --location 'https://pay.guesty.com/api/tokenize/v2' \
--header 'Content-Type: application/json' \
--data '{  
    "paymentProviderId": "61237062baf00000000000",
    "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"
    }
}

Response

Body ParameterData TypeDescription
_idstringThe ID of the newly tokenized card. It is a parameter in add payment method API.
threeDSobjectContains the authentication URL ("authURL").

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 or noauthURL is returned in the response (the issuer didn't require it), you may include the _id in the Create payment method request as outlined in OPTION 2.

Response example

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

Tokenizing a Stripe Payment Method Externally

Follow the steps below to generate a Stripe payment token.

Step 1: Connect a Stripe Account

Before Guesty can process Stripe payments for bookings, a Stripe account must be connected to your Guesty account. Learn more.

Step 2: Create a Stripe Payment Token

Generate a payment token from the connected Stripe account assigned to the Guesty listing.

🚧

Note

Take care to create only the payment token in Stripe, and not the customer (guest).

You now have a token to submit as a guest payment method, using OPTION 1.


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 reservation.