---
title: Bookly + Square Payment Integration
type: article
created: '2025-12-02'
updated: '2025-12-02'
source_docs:
- raw/2025-12-02-la-marie-beauty-project-call-105655411.md
tags:
- bookly
- square
- wordpress
- payment-integration
- woocommerce
- php
layer: 2
client_source: null
industry_context: null
transferable: true
---

# Bookly + Square Payment Integration

## Overview

Integrating Square as a payment gateway with Bookly requires custom PHP code to bridge the two systems. The core goal is to capture credit card information at checkout without necessarily charging the card immediately — a common pattern for service businesses that want to secure bookings with a card on file.

This integration is non-trivial. Bookly's native payment options do not include Square out of the box, so a custom PHP implementation is required to surface Square's payment fields within the Bookly checkout flow.

## Known Issues

### Credit Card Capture Failure

The most critical failure mode observed in practice: **custom PHP code that successfully books the appointment but silently skips credit card capture.**

In a live test on the [[clients/la-marie-beauty/_index|La Marie Beauty]] staging site (December 2025), the integration allowed a user to complete the booking flow and receive a confirmation — but no payment information was collected. The booking was created in the system with a $0 charge and no card on file.

**Symptoms:**
- Appointment is created in Bookly's calendar
- User receives a confirmation
- No credit card fields appear during checkout
- No payment record in Square dashboard

**Root cause:** The PHP hook into Bookly's checkout process was incomplete. The code registered the appointment but did not inject Square's card tokenization fields or submit the token to Square's API.

**Resolution required:** The PHP integration must:
1. Inject Square's Web Payments SDK card fields into the Bookly checkout step
2. Tokenize the card on form submission
3. Either charge the card or store the token (nonce) against the booking record

## Integration Architecture

```
User selects service → Bookly modal/flow → Custom checkout step
                                                    ↓
                                        Square Web Payments SDK
                                        (card fields rendered here)
                                                    ↓
                                        Card tokenized client-side
                                                    ↓
                                        PHP sends nonce to Square API
                                        (charge or store on file)
                                                    ↓
                                        Bookly appointment confirmed
```

## Implementation Notes

- Bookly exposes hooks for customizing the checkout step; the exact filter/action depends on the Bookly version in use
- Square's Web Payments SDK must be enqueued via `wp_enqueue_script` and initialized with the application ID and location ID
- The card nonce (token) is generated client-side and must be passed to a server-side PHP handler via AJAX or form POST before Bookly finalizes the booking
- For "card on file" (no immediate charge), use Square's Cards API to store the card; for immediate charge, use the Payments API

## Related Constraints

- This integration was built in the context of a WordPress + Bookly setup; it is not a WooCommerce flow
- The `/services` page uses Bookly shortcodes, not WooCommerce product pages
- Square sandbox credentials should be used for all staging testing; confirm environment switching before going live

## Open Questions (as of 2025-12-02)

- [ ] Should the card be charged at booking, or stored on file and charged at time of service?
- [ ] What is the fallback if Square tokenization fails mid-booking?
- [ ] Does Bookly's multi-service cart flow (if achievable) require one Square transaction or multiple?

## Related Articles

- [[clients/la-marie-beauty/_index|La Marie Beauty — Client Overview]]
- [[clients/la-marie-beauty/bookly-ux-scope-misalignment|Bookly UX & Scope Misalignment]]
- [[knowledge/woocommerce/bookly-custom-booking-flow|Bookly Custom Booking Flow (Cart-First UX)]]