Skip to content
Gaurav TiwariDocs

Square

Version 1.0.0-beta.1 Updated November 8, 2026

If you already take payments in person with Square, a second processor for your downloads means two payout schedules, two dashboards and customer cards saved in one place but not the other.

The Square module puts the card form from Square’s Web Payments SDK on the EDD checkout, with Apple Pay and Google Pay above it. Cards are saved on file with Square for one-click payments and automatic subscription renewals. The webhook that keeps refunds and card changes in sync is created for you when you save the settings.

Turn On the Gateway

  1. Switch on the Square module under Stackless → Dashboard.
  2. Add your application details under Stackless → Settings → Square and save.
  3. Go to Downloads → Settings → Payments and switch on Square (Stackless) under Active Gateways. Save.

Square stays off the checkout until the selected mode has an application ID, an access token and a location. EDD’s own Square gateway is a separate gateway with its own customers, cards and webhook, so both can be switched on at once. The gateway is in Stackless Lite for EDD too. Automatic renewals need the Subscriptions module in Stackless for EDD.

Connect Your Square Application

Click Open the Square Developer Console on the settings screen and open your application, or create one. Copy its application ID and access token for Production and for Sandbox. Then fill in the Square application section:

  • Sandbox: uses the Square sandbox, so no real money moves. On by default.
  • Production application ID, Production access token, Production location ID and Production webhook signature key
  • Sandbox application ID, Sandbox access token, Sandbox location ID and Sandbox webhook signature key

Leave the location IDs and webhook signature keys empty: saving fills them in. The access token from your application is a personal access token, which Stackless needs to create the webhook.

You can also set these as wp-config.php constants, which win over saved settings and hide their fields: STACKLESS_EDD_SQUARE_LIVE_APP_ID, STACKLESS_EDD_SQUARE_LIVE_ACCESS_TOKEN, STACKLESS_EDD_SQUARE_LIVE_LOCATION_ID, STACKLESS_EDD_SQUARE_LIVE_WEBHOOK_SIGNATURE_KEY and the same four with SANDBOX in place of LIVE.

What Saving Sets Up

Saving with an access token does two things for each mode:

  • Location and currency: Stackless reads the location you entered, or your main location when the field is empty, and fills in its ID. It must be an active location with card processing. The Checkout section then shows “Charging through [location] in [currency].”
  • Webhook: with the signature key empty, Stackless creates a webhook subscription named “Stackless for EDD” for https://yoursite.com/wp-json/stackless-edd/v1/square/webhook and saves its signature key. If one for this URL already exists, it gets a fresh key, since Square only shows a key when it’s made. The Webhook section then shows “Production webhook: signature key saved.” or the same for Sandbox.

With the gateway switched on, a missing application ID, access token or webhook signature key for the selected mode shows an error.

Add the Webhook by Hand

The webhook is only created on a public HTTPS site. On a local site the Webhook section shows “not set up yet.” Once the site is live, save again, or add it by hand: in your application, open Webhooks → Subscriptions, add your webhook URL with these events and paste its signature key into the matching field:

payment.updated
refund.created
refund.updated
card.disabled
card.forgotten
card.automatically_updated

Square signs each delivery over the webhook URL plus the body (x-square-hmacsha256-signature). Both signature keys are tried, and the one that matches decides the mode. Each event is applied once. If your site address changes, empty the signature key fields and save again, so a webhook is created for the new address.

The Location Currency Rule

Square charges only in the currency of your Square location, which follows the seller’s country. Square takes online payments in USD, CAD, GBP, AUD, JPY and EUR.

  • Square hides itself when the cart is in another currency.
  • With multi-currency, Square tells Currency-Aware Payment Gateways that it takes the location’s currency only.
  • Billing Health shows a note when your store currency differs from the location’s.

What Buyers See

The Checkout section sets what buyers see:

  • Title: the payment method name at checkout. Default “Card, Apple Pay or Google Pay”.
  • Description: shown above the card form. Default “Pay securely with your card through Square.”
  • Wallets: Google Pay and Apple Pay buttons above the card form on one-time orders. Both on by default.
  • Saved cards: lets signed-in customers save cards with Square. Subscription orders always save the card. On by default.
  • Square’s card form loads from Square, and card details go from the browser to Square. Your store only receives a one-time token.
  • Square’s buyer verification runs with the billing details when the buyer clicks Purchase, so banks that want 3-D Secure get it.
  • Signed-in customers see their saved cards with “Use a new card” at the end and, with Saved cards on, a “Save this card to my account for future purchases.” box.
  • The payment is taken right away. A payment that doesn’t match the order total puts the order on hold with a note.
  • Declines show a plain message, such as “Your card has insufficient funds.”
  • Sandbox adds “Sandbox: use Square’s test cards; no real payment will be taken.”

Apple Pay and Google Pay

Apple Pay needs your domain registered in the Square Developer Console, on your application’s Apple Pay tab. Apple Pay only works on an HTTPS domain.

Wallet payments can’t be saved, so subscription checkouts and Add a card on the account page show the card form only.

Saved Cards and Subscriptions

  • A subscription checkout always saves the card on file with a Square customer. The card is saved from the payment before the order is marked paid, so the subscription has it from the start.
  • A free trial with nothing to pay today still offers Square and saves the card without charging it.
  • Renewals charge the saved card as merchant-initiated, without the customer present. If Square can’t be reached, the charge is retried up to 3 more times, 15, 30 and 45 minutes apart, with the same idempotency key so the customer isn’t charged twice.
  • A declined renewal is marked Failed with Square’s reason, and your retry schedule takes over. Renewals, Failed Payments and Retries covers what happens next.
  • A saved card picked at checkout is charged without a new verification step. When the bank asks for one, the buyer sees “Your bank needs you to verify this payment. Enter your card details again to continue.”
  • Saved cards also pay for Post-purchase Offers. If the bank wants verification there, the buyer is sent to checkout to enter the card for that order.
  • Customers see their cards under “Cards saved with Square” in the Payment methods tab on the account page. They can add a card, make one the default or delete one. Deleting a card disables it at Square.
  • Customers can change a subscription’s card from the subscription portal.
  • When Square disables or forgets a card, the saved card is removed in EDD. When Square’s card updater changes a card, its brand, expiry date and last four digits are updated.
  • Sandbox and production cards are kept apart.

Refunds

Refund from the EDD order screen, in full or in part. The refund form gets a Refund the payment in Square box, ticked by default. Square is called before EDD records the refund, so a refund Square refuses stops there with the error. Untick the box to record the refund in EDD only.

Refunds made in the Square Dashboard are recorded on the order through the webhook, and a refund Square rejects adds a note.

Billing Health

Square reports to Billing Health: a missing application ID, access token or location for the selected mode, a missing webhook signature key, a store currency that differs from the location’s, sandbox mode and webhooks that failed recently. A missing webhook comes with a Create the webhook button. Square retries a failed delivery for 24 hours.

Limits

  • Square takes one currency, the location’s. Carts in other currencies don’t see it.
  • Apple Pay and Google Pay payments can’t be saved, so subscriptions need a card.
  • Apple Pay needs your domain registered in the Square Developer Console.
  • A saved card at checkout isn’t verified again. When the bank asks for verification, the buyer enters the card again.
  • The webhook is created automatically only on a public HTTPS site with a personal access token.
  • Disputes opened in Square aren’t brought into EDD.
  • On a site Stackless treats as a copy of the live store, such as a staging clone, saved payment methods aren’t charged.
  • Square can’t be duplicated with Payment Gateway Tools. Its cards and customers belong to one Square account.
  • Turn on Debug log in the Checkout section to write Square activity to Downloads → Tools → Debug Log, tagged stackless-edd-square_gateway. Errors are always logged. Tokens and card data never are.

For Developers

stackless_edd_square_gateway_webhook runs after each webhook event is applied, with the event type, the event and the mode:

add_action('stackless_edd_square_gateway_webhook', function ($type, $event, $mode) {
    if ($type === 'refund.created' && $mode === 'live') {
        // Notify your accounting tool.
    }
}, 10, 3);

Refunds created in code reach Square only when stackless_edd_refund_at_gateway returns true. Copy templates/square_gateway/payment-fields.php to yourtheme/stackless-edd/square_gateway/payment-fields.php to change the card form. Keep its element ids and the data-config attribute, which the script reads.

Share

Was this helpful?

Still stuck? Open a support ticket