Payment Tokenization in WooCommerce

Overview

When building a unified WooCommerce checkout that handles both product purchases and service bookings, a key requirement is the ability to capture a credit card at checkout without immediately charging it — and then charge that card later (e.g., at time of service, or if a no-show fee applies). This is distinct from simply processing a zero-dollar transaction.

This pattern is sometimes called payment tokenization: storing a card reference (token) that can be used for future charges, without storing raw card data.

The Problem

WooCommerce itself does not natively store credit card details for future charges. It delegates payment processing entirely to third-party gateways (Stripe, Square, etc.). The challenge is that:

The gateway (e.g., Square) has the tokenization infrastructure and bank relationships.
WooCommerce's checkout UI does not expose a "save card for later" option by default.
Simply setting the order subtotal to zero (to allow a free booking reservation) does not capture a card token — it just processes a $0 transaction.

This distinction surfaced during the ^[1] project, where engineer Ishak built a unified checkout that correctly shows the service price but sets the subtotal to zero, allowing product payment while reserving the service slot. However, the ability to re-charge that card later remained unresolved.

"The actual saving of the credit card through WooCommerce, where we use some sort of tokenization, where we then are able to recharge that card — I'm not sure that we've found that solution yet."
— Chris Østergaard, 2025-11-11 call

Investigation Paths

1. Native WooCommerce Plugin Feature

Some WooCommerce payment gateway plugins (particularly the official WooCommerce Square plugin) include built-in tokenization support. This may surface as a "Save card for future use" checkbox in the checkout form. The key questions to verify:

Does the installed Square gateway plugin support tokenization?
Is tokenization enabled in the plugin settings?
Does the token persist and remain chargeable even on a $0 order?

2. Custom Hook / Code Solution

If native plugin support is insufficient, a custom hook may be required. WooCommerce provides action and filter hooks throughout the checkout and order lifecycle. Relevant hooks to investigate:

woocommerce_payment_token_create — fires when a token is saved
woocommerce_add_payment_method — for explicitly saving a payment method
Custom integration with Square's Cards API to create a card-on-file directly

This approach requires more development effort but gives full control over when and how the card is stored.

3. Square Cards API (Direct Integration)

Square has a dedicated Cards API for storing cards on file. If WooCommerce's gateway plugin does not expose tokenization natively, a custom integration could:

Collect card details via Square's Web Payments SDK at checkout.
Store the card on file via the Cards API.
Return a card_id to be associated with the WooCommerce order or customer record.
Use that card_id for future charges via the Payments API.

This is the most robust path but requires the most custom development.

Open Questions (as of 2025-11-11)

[ ] Does the WooCommerce Square plugin version in use support tokenization on $0 orders?
[ ] Is there a native "save card" checkbox that simply needs to be enabled in settings?
[ ] If a custom hook is needed, which hook in the WooCommerce lifecycle is the correct insertion point?
[ ] How does Square handle a card-on-file token when the originating order had a $0 subtotal?

Owner: Ishak (engineer) — investigating as of the 2025-11-11 call. Results to be presented at the following week's meeting.

This question arose in the context of a broader architecture where:

Bookly handles appointment scheduling
WooCommerce handles the unified checkout (products + service reservations)
Square is the source of truth for staff calendars and payment processing

See ^[2] for the full system design.

The tokenization requirement exists because La Marie Beauty needs to hold a card on file for potential no-show charges — a common pattern in appointment-based businesses.

^[2]
^[3]
^[4]
^[5]