---
title: LaMarie Custom Payment Flow — Card-on-File & Square Integration
type: article
created: '2026-04-05'
updated: '2026-04-05'
source_docs:
- raw/2025-11-18-la-marie-beauty-project-call-102533137.md
tags:
- woocommerce
- square
- bookly
- php
- payment
- card-on-file
- la-marie-beauty
- custom-code
layer: 2
client_source: null
industry_context: null
transferable: true
---

# LaMarie Custom Payment Flow — Card-on-File & Square Integration

## Overview

The La Marie Beauty booking system requires a custom payment flow that neither Bookly nor WooCommerce can handle natively. The core requirement is a **mixed cart** supporting both products (charged immediately) and services (card stored but not charged at booking). Custom PHP code using Square's APIs bridges this gap.

This pattern was confirmed during a technical review call with developer Isahaque Mahmud and PM Kimberly Gehrmann. See [[clients/la-marie-beauty/_index]] for project context.

---

## Business Requirements

The cart must support three purchase types simultaneously:

| Cart Contents | Payment Behavior |
|---|---|
| Products only | Charged in full at checkout |
| Services only | Card stored; no immediate charge |
| Mixed (products + services) | Products charged immediately; service card stored for later |

**Service-specific payment rules:**
- Card is **not charged at booking**
- Card is **tokenized and stored** for:
  - No-show penalties
  - Cancellation fees
  - Final payment after service is rendered

---

## Technical Implementation

### Why Custom PHP Is Required

Bookly and WooCommerce do not natively support deferred service charges or card-on-file without immediate payment. The only path to implement this flow is custom PHP code hooking into WordPress/WooCommerce's plugin system.

> *"For all those type of payment, we need to write some custom PHP code."* — Isahaque Mahmud

WordPress and WooCommerce expose a **hook system** (actions and filters) that is PHP-only. Any backend customization — including payment flow logic — must use these hooks, making PHP non-negotiable for the server-side implementation.

### Square API Integration

Rather than building fully custom card handling, the implementation uses **Square's APIs for card tokenization**. This was an explicit recommendation from Kimberly Gehrmann to preserve two things:

1. **Security posture** — Square's infrastructure handles PCI-sensitive card data; custom code never touches raw card numbers
2. **Customer profiles** — Square maintains customer records (name, phone, email auto-fill) that would be lost if card handling were fully bespoke

The developer (Isahaque) confirmed this is achievable via Square API keys, which can be generated without requiring action from the client.

### Implementation Status (as of call date)

- Custom PHP for the service payment flow had **not yet been started** at the time of this call
- Action item assigned to Isahaque: begin development using Square APIs for tokenization
- Frontend variation logic (JavaScript for service pages) was already partially written — see [[knowledge/javascript/lamarie-service-page-variation-js]]

---

## Architecture Notes

```
Customer Checkout
    │
    ├── Product in cart?
    │       └── WooCommerce standard charge (immediate)
    │
    └── Service in cart?
            └── Custom PHP hook
                    └── Square API: tokenize card → store on customer profile
                            └── No charge triggered at booking
                            └── Card available for post-service charge / penalties
```

**Key constraint:** The Square API key is managed by the developer, not provisioned by the client. The client's Square account must be connected, but key creation is a developer task.

---

## Related Decisions

- **Bookly ↔ Square availability sync** is real-time via API, eliminating double-booking risk. See [[knowledge/bookly/square-availability-sync]].
- **Service page content** (images, text, Book Now destination) is controlled by custom JavaScript — a separate maintenance concern. See [[knowledge/javascript/lamarie-service-page-variation-js]].
- **Bookly widget customization** is limited to existing elements (colors, fonts, reordering, removing). New elements (buttons, icons) cannot be added. See [[knowledge/bookly/widget-customization-limits]].

---

## Risks & Considerations

| Risk | Notes |
|---|---|
| PHP maintenance burden | Kimberly flagged she can read PHP but prefers JS; Isahaque confirmed PHP is required for WooCommerce hooks |
| Square API key management | Developer-held; needs handoff documentation before Asymmetric rolls off |
| Scope of custom code | Not yet written at call date; complexity unknown until implementation begins |

---

## Action Items (from source call)

- [ ] **Isahaque** — Begin custom PHP development for service payment flow using Square APIs for card tokenization
- [ ] **Melissa** — Ensure Kimberly has full WordPress staging site access (confirmed resolved during call)
- [ ] **Kimberly** — Review custom JavaScript on service pages to assess long-term maintenance complexity before Asymmetric handoff

---

## Source

- Meeting: *La Marie Beauty — Booking & Payment System Technical Review* (2026-04-05)
- Attendees: Kimberly Gehrmann (external PM), Isahaque Mahmud (Asymmetric dev), Melissa Cusumano (Asymmetric PM), Roxana Lopez (LMB)
- Recording: https://fathom.video/calls/477300762