Bookly $0 Service Card Capture Pattern

Overview

A common requirement for appointment-based businesses is capturing a credit card on file during booking for a zero-dollar service — typically to enable pre-appointment authorization or no-show protection. Implementing this flow through Bookly with Square as the payment processor is non-trivial and has known failure modes.

This article documents what is known about the pattern, where it breaks down, and the investigation status as of December 2025.

The Desired Flow

1. Customer selects a service priced at $0 (e.g., a free consultation or intake appointment).
2. During the Bookly booking flow, the customer is prompted to enter credit card details.
3. The booking completes successfully.
4. The card data is stored in Square for later use (pre-authorization, charging for no-shows, etc.).

This is a legitimate and well-documented use case in the appointment booking space. The challenge lies in whether Bookly's Square integration supports it natively.

Known Failure Point

In testing on the ^[1] project, the booking flow completes without error — but the card data does not appear in the Square dashboard. The transaction registers as complete on the Bookly/WordPress side, while Square receives no card information.

Developer finding (Eshock): After investigating the custom integration code, the conclusion was that the issue originates with Square's API behavior for $0 transactions, not with the custom code itself. Square may not process or store card data when the transaction amount is zero, depending on how the API call is structured.

Root Cause Hypotheses

1. Square API does not support $0 card-on-file capture via the standard Payments API. Square's card-on-file flow typically requires using the Cards API or Customer API separately from a payment transaction. A $0 charge may not trigger the card storage pathway.
2. Bookly's Square integration does not implement the Cards API. Bookly may only pass card data through the standard payment flow, which fails silently for $0 amounts.
3. Plugin limitation: Bookly may not natively support the $0 service + card capture combination, requiring custom API calls outside of what the plugin provides.

Investigation Status

As of the December 12, 2025 sync call, this issue is unresolved and actively blocked.

• Eshock spent significant time on the integration and coding the checkout flow, ultimately concluding the problem is with Square's API handling of $0 transactions.
• Kimberly Gehrmann committed to a deep-dive into Bookly's documentation over the following weekend to determine:
• Whether Bookly officially supports this workflow.
• Whether a plugin replacement or supplemental approach is warranted.
• The Loom walkthrough and Miro board prepared by Melissa Cusumano were shared as context for the investigation.

Potential Workarounds

These have not yet been validated but are worth exploring:

• Square Cards API (separate from Payments API): Create a customer record in Square and use the Cards API to tokenize and store the card independently of any payment transaction. Bookly would need to be extended or bypassed for this step.
• $0.01 authorization + void: Charge a nominal amount ($0.01) to capture the card, then immediately void the transaction. Hacky, but used in practice.
• Alternative booking plugins: If Bookly cannot support this natively, plugins with more flexible payment hooks (e.g., Amelia, WooCommerce Bookings) may offer better extensibility for custom Square API calls.
• Zapier / middleware layer: A Zapier or Make.com automation triggered on booking completion could call the Square Cards API to store the card — though this adds complexity and a dependency. (Note: Zapier is already a point of concern on the La Marie Beauty project; see ^[2].)

Related Issues on La Marie Beauty

• Zapier location bug: ~12 Square products had their location switched unexpectedly. Square support identified Zapier as the only possible cause, pointing to a lingering integration from a previous developer (Chris). See ^[2].
• New-line bug (resolved): A \n character was appearing in WooCommerce output. Root cause was the WooCommerce Matomo Analytics plugin, which was deactivated by Eshock.
• URL routing: Bookly's page route was changed from /services to /appointments to avoid conflict with the services tile page.

References

• Meeting: ^[3]
• Client: ^[1]