Skip to content

v3 Reference

Jump to bottom
Yurii Nikitiuk edited this page Sep 1, 2026 · 3 revisions

guestyTokenization.render(options)

Renders the Guesty tokenization form in the provided container element. The form is rendered in an iframe to ensure PCI compliance.

Returns a Promise that resolves after the iframe is loaded or is rejected if the iframe fails to load.

Options

containerId (required)

The ID of the container element within which the iframe will be rendered.

providerId (required)

The ID of the payment provider for which the form is rendered.

paymentMethod (optional)

Selects which payment method form to render. Defaults to card.

Supported values:

  • card
  • ach

onStatusChange (optional)

A callback function called when form validity changes. A boolean value is passed as an argument.

const onStatusChange = (isValid) => {
  // process value
};

styles (optional)

An object containing style variables to apply to the form.

Variable Description
fontFamily Font family used throughout the form
fontSizeBase Base font size used by typography tokens
fontSizeMd Font size used for regular text on the form
fontSizeLg Font size used for large text on the form
fontWeightRegular Font weight for regular text
fontWeightBold Font weight for bold text
borderRadius Border radius of the form input
inputHeight Height of the form input
inputPadding Padding of the form input
colorText Primary text color used throughout the form
colorTextError Text color used for error messages
colorPlaceholder Input placeholder color
colorBorder Border color of the form input
colorBorderFocus Border/focus ring color of the active form input
colorFormBackground Background color of the form
colorInputBackground Background color of form inputs

lang (optional)

Display language of the form elements. The default is en-US.

initialValues (optional)

Pre-fill form fields. Use card fields when paymentMethod is card (default), or bank fields when paymentMethod is ach. Billing address fields apply to both.

Card example:

{
  nameOnCard: 'John Doe',
  cardHolderId: '123456789', // optional; shown only for processors that require it (e.g. HYP / Israeli ID)
  cardNumber: '4111111111111111',
  expirationDate: '12/30',
  csc: '123',
  street: 'Main street',
  city: 'New York',
  state: 'NY',
  zipCode: '10001',
  country: { value: 'US', label: 'United States' }
}

ACH example:

{
  accountHolderName: 'John Doe',
  routingNumber: '123456789',
  accountNumber: '000123456789',
  accountType: '1', // '1' checking, '2' savings
  entityType: '0', // '0' personal, '1' business
  street: 'Main street',
  city: 'New York',
  state: 'NY',
  zipCode: '10001',
  country: { value: 'US', label: 'United States' }
}

inputsConfig (optional)

Customize labels and placeholders for supported form inputs.

Card example:

{
  nameOnCard: { label: 'Name on card', placeholder: 'John Doe' },
  cardNumber: { label: 'Card number', placeholder: '**** **** **** ****' },
  expirationDate: { label: 'Expiry', placeholder: 'MM/YY' },
  csc: { label: 'CVC', placeholder: '123' }
}

ACH example:

{
  accountHolderName: { label: 'Account holder', placeholder: 'John Doe' },
  routingNumber: { label: 'Routing number', placeholder: '123456789' },
  accountNumber: { label: 'Account number', placeholder: '000123456789' }
}

showReuseCheckbox (optional)

Shows checkbox to mark the payment method for future reuse.

showAddressToggle (optional)

Shows billing-address toggle.

showNameToggle (optional)

Shows name toggle.

addressToggleLabel, nameToggleLabel (optional)

Custom labels for corresponding toggles.

showSupportedCards (optional)

Display section with supported card brands.

showPciCompliantLink (optional)

Display PCI compliance note.

guestyTokenization.validate()

Triggers the validation of the form fields and displays error messages if any. Returns void.

guestyTokenization.submit(payload)

Triggers validation and, if valid, submits the form. Returns a Promise that resolves with the payment method or rejects with an error.

For ACH, the payload is ignored and an empty object is sent internally.

Card payload

Pass reservationId when tokenizing against an existing reservation, or quoteId with guest when tokenizing in the context of a quote

With reservationId:

{
  amount: 100,
  currency: 'USD',
  listingId: 'LISTING_ID',
  reservationId: 'RESERVATION_ID',
  apiVersion: 'v3',
  method: 'verify_no_3ds'
}

With quoteId and guest:

{
  amount: 100,
  currency: 'USD',
  listingId: 'LISTING_ID',
  quoteId: 'QUOTE_ID',
  guest: {
    firstName: 'John',
    lastName: 'Doe',
    email: 'john@example.com',
    phone: '+15551234567'
  },
  apiVersion: 'v3',
  method: 'verify_no_3ds'
}
Field Required Notes
listingId Yes* Required unless apiVersion: 'v2'
reservationId One of Use when a reservation already exists
quoteId One of Use when tokenizing in the context of a quote; requires guest.firstName and guest.lastName
amount Yes Payment amount
currency Yes Payment currency (e.g. 'USD')
guest Conditional Required when using quoteId
apiVersion No 'v2' or 'v3' (default behavior is v3)
method No 'verify' (default) or 'verify_no_3ds'. Use 'verify_no_3ds' when tokenizing ahead of an instant charge — 3DS authentication is handled later during the charge via handle3DSChallenge, not at tokenization time. Applies with either reservationId or quoteId.

ACH payload

ACH submit payload is empty in SDK v3:

{}

guestyTokenization.destroy()

Destroys the iframe and removes it from the DOM. Removes all event listeners and clears any in-progress 3DS challenge state.

guestyTokenization.handle3DSChallenge(options)

Handles a 3DS challenge after tokenization when a payment requires additional authentication. Returns a Promise that resolves with the challenge result or rejects on failure, timeout, or user cancellation.

Use this when the backend returns threeDSChallenge on a payment authorization response (for example, when payment status is PENDING_AUTH).

The SDK renders and cleans up the challenge UI itself — you do not need to provide a container or build your own modal. The challenge UI is removed automatically when the challenge completes, fails, or is cancelled.

Options

threeDSChallenge (required)

Opaque challenge payload returned by the Guesty backend. Pass it through as received — do not construct or modify it on the client.

const challengeResult = await guestyTokenization.handle3DSChallenge({
  threeDSChallenge: paymentResponse.threeDSChallenge,
});

// Pass the result back to your backend to complete authorization
await verifyPayment({ paymentId, threeDSResult: challengeResult });

Errors

The Promise rejects when:

  • The user dismisses the challenge (3DS authentication cancelled)
  • Authentication fails (3DS authentication failed)
  • Authentication times out (3DS authentication timeout)

Instant charge flow

Typical sequence when tokenizing with method: 'verify_no_3ds' and charging immediately after (instant charge):

  1. render() — show the tokenization form
  2. submit() — tokenize the payment method (quoteId or reservationId depending on your integration)
  3. Create/charge the reservation on your backend using the returned payment method
  4. If the backend returns threeDSChallenge, call handle3DSChallenge({ threeDSChallenge })
  5. Send the challenge result to your backend verify endpoint
  6. destroy() when done

Clone this wiki locally