pay-square 0.1.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94a7592d85a226f50c70b335728f80342fb8238da4625b0143e3e8ee5fd47ec1
+  data.tar.gz: 6d1ee0770171be37469056cb15a23ed5a6c7a699fa864725ff30be5a5ff670b0
+SHA512:
+  metadata.gz: 35c828140e98a9469cf68afa423cfa0e00294ddb95c0c6ac8b92e79ec1f9faff5fe4d3d4f0a1e78f20ee669125d4125d65776075e7803efa4281f374c57928e4
+  data.tar.gz: e6f863aa1776fe3168a8550927ec83a25ab2188063f5a36389c830d0c3f53f2b03a0975b51fadf386b8467383dff0a866a677db2571e6b038ae268fdc4b2a293

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## Unreleased
+
+* Adopted Pay's `.github` conventions: a `Standardrb` lint job in CI, a reusable `ci.yml`
+  (`workflow_call`) that the publish workflow runs before releasing, per-job timeouts, and
+  `actions/checkout@v6`. Renamed `release.yml` to `publish_gem.yml`.
+* Added `.standard.yml` (ignoring the generated dummy app), `dependabot.yml` (bundler + GitHub
+  Actions, monthly), a pull request template, and bug/feature issue templates.
+
+* Added CI (`.github/workflows/ci.yml`): runs the test suite on every pull request and push to
+  `main`, across Ruby 3.1–3.4 and Pay 11 + 12, behind a single `All tests passed` check.
+* The release workflow now runs the tests first and only publishes to RubyGems if they pass.
+* `Gemfile` honors `PAY_VERSION` so CI can pin the Pay major under test.
+
+* Added trusted-publishing release workflow (`.github/workflows/release.yml`): a `v*` tag push
+  publishes to RubyGems via OpenID Connect, no stored API key. See `RELEASING.md`.
+* Removed the generated `gem-push.yml` starter workflow in favor of `release.yml` (it published on
+  every push to main, pinned Ruby 2.6, and also pushed to GitHub Packages).
+* README: added gem version / Ruby / license badges and a Links section; vendored the RubyGems
+  logos under `assets/rubygems/`.
+* README reorganized to follow Pay's conventions: Pay logo + tagline, badges on one line, a blockquote
+  for the upstream endorsement, and a `📚 Docs` section linking to dedicated pages under `docs/`
+  (installation, configuration, usage, webhooks).
+* gemspec now sets `rubygems_mfa_required`, and drops the duplicate `homepage_uri` metadata.
+
+## 0.1.0.rc1 - 2026-10-21
+
+First pre-release, cut for verification in a real consuming app before `0.1.0` is tagged
+(see [RELEASING.md](RELEASING.md) for our pre-release policy).
+
+* Compatible with Pay 11.x and 12.x (verified against Pay 11.7.2 and 12.3.0).
+* The Square SDK (`square.rb`) is an app-provided dependency, matching Pay's convention for its
+  built-in processors. Add `gem "square.rb", "~> 44"` to your app's Gemfile; `pay-square` no longer
+  declares it and no longer `require`s it (the processor gates on `defined?(::Square)`).
+* Added `RELEASING.md` (versioning and tag conventions) and `CONTRIBUTING.md`; documented release
+  and pre-release pinning in the README.
+* Fixed test suite boot order so the dummy app's environment loads before the gem.
+* Initial release: Square payment processor for Pay.
+  * Charge on a merchant's own connected Square account (per-merchant OAuth) via a
+    configurable `Pay::Square.access_token_provider`; a `Square::Client` is built per
+    operation and retries once with a refreshed token on a 401.
+  * Card-on-file (Cards API), charges (`CreatePayment`) with optional `app_fee_money`,
+    and refunds.
+  * Pay-mounted `/pay/webhooks/square` endpoint with HMAC signature verification; handlers
+    re-fetch authoritative state (Square delivery is unordered).
+  * Adds a `square_account` column to scope customers per merchant, with cross-merchant
+    isolation in `set/add_payment_processor`.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Willard Moore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+<p align="center">
+  <a href="https://github.com/pay-rails/pay"><img src="https://raw.githubusercontent.com/pay-rails/pay/main/docs/images/logo.svg" height="50px" alt="Pay"></a>
+</p>
+
+# 💳 Pay::Square — Square for the Pay gem
+
+[![Gem Version](https://img.shields.io/gem/v/pay-square?logo=rubygems&logoColor=white)](https://rubygems.org/gems/pay-square) [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D?logo=ruby&logoColor=white)](pay-square.gemspec) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](MIT-LICENSE)
+
+A **[Square](https://squareup.com/)** payment processor for **[Pay — the payments engine for Ruby on Rails](https://github.com/pay-rails/pay)**.
+
+## 🏦 Extending Pay — and why Square is its own gem
+
+[Pay](https://github.com/pay-rails/pay) already speaks Stripe, Braintree, Paddle, and Lemon Squeezy.
+`pay-square` adds **Square** from the outside — its own gem, no fork of Pay — the same self-registering
+plugin pattern as [`pay-asaas`](https://github.com/PedroAugustoRamalhoDuarte/pay-asaas).
+
+Pay's maintainer, Chris Oliver, both welcomed this and is taking the same direction for Pay's own
+processors:
+
+> I'm planning to extract Braintree and Paddle from the main gem. It doesn't bloat anything having them
+> in the gem since they're lazy loaded, but easier to maintain. […] long-term we can add it to the pay
+> org if you would like to keep maintaining it.
+>
+> — [Chris Oliver, pay-rails/pay#1251](https://github.com/pay-rails/pay/pull/1251#issuecomment-5545503069)
+
+### Not just a processor — a marketplace integration
+
+Braintree and Paddle are being split out for maintainability alone. Square is a different case: here it
+is used for **[marketplace payments](https://github.com/pay-rails/pay/tree/main/docs/marketplaces)** —
+Pay's term for charging on a connected merchant's **own account** and taking an **application fee** —
+not merely to charge your own customers.
+
+Square also issues a **distinct OAuth access token per merchant** (unlike Stripe Connect's single
+platform key plus a `stripe_account` header). So `pay-square` charges on a merchant's **own connected
+Square account** (the merchant, not you, is the merchant of record), building a `Square::Client` per
+operation from a token you supply via `Pay::Square.access_token_provider`, and isolates customers per
+merchant with a `square_account` column. That on-behalf-of, per-merchant model — not plain processing —
+is a core reason Square belongs in its own gem.
+
+Scope: card payments, card-on-file, refunds, and payment/refund/card/customer webhooks. Square OAuth,
+token refresh, payouts/reconciliation, catalog, and the checkout UI stay in your app.
+
+## 📋 Requirements
+
+- Ruby >= 3.1.0
+- [Pay](https://github.com/pay-rails/pay) 11.x or 12.x (verified against 11.7.2 and 12.3.0)
+- [square.rb](https://github.com/square/square-ruby-sdk) ~> 44
+
+## 📚 Docs
+
+- [Installation](docs/installation.md) — Gemfile, pre-releases, and the migration
+- [Configuration](docs/configuration.md) — the per-merchant token resolver and credentials
+- [Usage](docs/usage.md) — charges, card-on-file, refunds, and per-merchant isolation
+- [Webhooks](docs/webhooks.md) — endpoint, signature verification, and handled events
+- [Versioning & releasing](RELEASING.md) — SemVer, tags, pre-releases, and publishing
+- [Contributing](CONTRIBUTING.md) — dev setup, running the tests, and opening issues
+
+## 🙏 Contributing
+
+Bug reports, feature ideas, and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) to
+get started.
+
+## 🔗 Links
+
+[<img src="assets/rubygems/rubygems_logo_red.png" alt="RubyGems" height="24" align="left">](https://rubygems.org/gems/pay-square)
+
+[pay-square on RubyGems](https://rubygems.org/gems/pay-square) · [Changelog](CHANGELOG.md)
+
+The RubyGems and Pay logos are trademarks of their respective projects, used here to link to those
+projects, not to imply endorsement.
+
+## 📝 License
+
+MIT.

data/Rakefile

@@ -0,0 +1,15 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/pay/webhooks/square_controller.rb

@@ -0,0 +1,48 @@
+module Pay
+  module Webhooks
+    class SquareController < ActionController::API
+      def create
+        if valid_signature?(request.headers["x-square-hmacsha256-signature"])
+          queue_event(verify_params.as_json)
+          head :ok
+        else
+          head :bad_request
+        end
+      rescue Pay::Square::Error
+        head :bad_request
+      end
+
+      private
+
+      def queue_event(event)
+        return unless Pay::Webhooks.delegator.listening?("square.#{params[:type]}")
+
+        record = Pay::Webhook.create!(processor: :square, event_type: params[:type], event: event)
+        Pay::Webhooks::ProcessJob.perform_later(record)
+      end
+
+      # Square signs the HMAC-SHA256 over (notification_url + raw body), base64-encoded.
+      # notification_url must match the URL registered with Square; behind a proxy
+      # request.original_url may differ, so it is configurable.
+      def valid_signature?(signature)
+        return false if signature.blank?
+
+        key = Pay::Square.signing_secret
+        return false if key.blank?
+
+        data = notification_url + request.raw_post
+        digest = OpenSSL::Digest.new("sha256")
+        hmac = Base64.strict_encode64(OpenSSL::HMAC.digest(digest, key, data))
+        ActiveSupport::SecurityUtils.secure_compare(hmac, signature)
+      end
+
+      def notification_url
+        Pay::Square.webhook_notification_url.presence || request.original_url
+      end
+
+      def verify_params
+        params.except(:action, :controller).permit!
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,3 @@
+Pay::Square::Engine.routes.draw do
+  post "webhooks/square", to: "pay/webhooks/square#create" if Pay::Square.enabled?
+end

data/db/migrate/20250901000001_add_square_account_to_pay_models.rb

@@ -0,0 +1,10 @@
+class AddSquareAccountToPayModels < ActiveRecord::Migration[7.0]
+  # Scopes a Pay::Customer / PaymentMethod / Charge to a Square merchant (mirrors
+  # stripe_account). Install into your app with:
+  #   bin/rails pay_square:install:migrations && bin/rails db:migrate
+  def change
+    add_column :pay_customers, :square_account, :string
+    add_column :pay_payment_methods, :square_account, :string
+    add_column :pay_charges, :square_account, :string
+  end
+end

data/lib/pay/square/attributes.rb

@@ -0,0 +1,39 @@
+module Pay
+  module Square
+    # Pay's core set/add_payment_processor dedup key is hardcoded and does not know about
+    # square_account. We prepend to include it for the :square processor so one owner
+    # transacting with two Square merchants gets two isolated Pay::Customers (the same
+    # guarantee stripe_account provides via #1198). Everything else delegates to super.
+    module Attributes
+      def set_payment_processor(processor_name, square_account: nil, **options)
+        return super(processor_name, **options) unless processor_name.to_sym == :square
+
+        with_lock do
+          pay_customers.update_all(default: false)
+          pay_customer = pay_customers.active.where(
+            Pay::Customer.inheritance_column => "Pay::Square::Customer",
+            :processor => "square",
+            :square_account => square_account
+          ).first_or_initialize
+          pay_customer.update!(options.merge(default: true))
+        end
+
+        reload_payment_processor
+      end
+
+      def add_payment_processor(processor_name, square_account: nil, **options)
+        return super(processor_name, **options) unless processor_name.to_sym == :square
+
+        pay_customer = pay_customers.active.where(
+          Pay::Customer.inheritance_column => "Pay::Square::Customer",
+          :processor => "square",
+          :square_account => square_account
+        ).first_or_initialize
+        pay_customer.update!(options)
+        pay_customer
+      end
+    end
+  end
+end
+
+Pay::Attributes::CustomerExtension.prepend(Pay::Square::Attributes)

data/lib/pay/square/charge.rb

@@ -0,0 +1,78 @@
+module Pay
+  module Square
+    class Charge < Pay::Charge
+      store_accessor :data, :square_order_id
+      store_accessor :data, :square_status
+      store_accessor :data, :square_merchant_id
+
+      # Re-fetches authoritative payment state (webhook delivery is unordered), unless a
+      # freshly created payment is passed in.
+      def self.sync(payment_id, object: nil, pay_customer: nil, try: 0, retries: 1)
+        object ||= Pay::Square.with_client(pay_customer) { |client| client.payments.get(payment_id: payment_id) }.payment
+        return if object.nil?
+
+        pay_customer ||= Pay::Customer.find_by(processor: :square, processor_id: object.customer_id)
+        if pay_customer.nil?
+          Rails.logger.debug "Pay::Customer for Square payment #{payment_id} (customer #{object.customer_id}) is not in the database"
+          return
+        end
+
+        card = object.card_details&.card
+        attrs = {
+          amount: object.amount_money&.amount,
+          currency: object.amount_money&.currency&.downcase,
+          application_fee_amount: object.app_fee_money&.amount,
+          amount_refunded: object.refunded_money&.amount || 0,
+          payment_method_type: "card",
+          brand: card&.card_brand,
+          last4: card&.last_4.to_s,
+          exp_month: card&.exp_month&.to_s,
+          exp_year: card&.exp_year&.to_s,
+          square_account: pay_customer.square_account,
+          square_order_id: object.order_id,
+          square_status: object.status,
+          square_merchant_id: (object.respond_to?(:merchant_id) ? object.merchant_id : nil)
+        }
+        attrs[:created_at] = Time.zone.parse(object.created_at.to_s) if object.respond_to?(:created_at) && object.created_at.present?
+
+        if (pay_charge = find_by(customer: pay_customer, processor_id: object.id))
+          pay_charge.with_lock { pay_charge.update!(attrs) }
+          pay_charge
+        else
+          create!(attrs.merge(customer: pay_customer, processor_id: object.id))
+        end
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique
+        if try >= retries
+          raise
+        else
+          sleep 0.15**(try + 1)
+          retry_args = {object: object, pay_customer: pay_customer, try: try + 1, retries: retries}
+          sync(payment_id, **retry_args)
+        end
+      end
+
+      def api_record
+        Pay::Square.with_client(customer) { |client| client.payments.get(payment_id: processor_id) }.payment
+      end
+
+      # Square refunds are asynchronous (PENDING -> COMPLETED, can fail), so re-sync
+      # amount_refunded from the payment rather than optimistically incrementing.
+      def refund!(amount_to_refund = nil, **options)
+        amount_to_refund ||= amount
+        idempotency_key = options.delete(:idempotency_key) || SecureRandom.uuid
+
+        Pay::Square.with_client(customer) do |client|
+          client.refunds.refund_payment(
+            idempotency_key: idempotency_key,
+            payment_id: processor_id,
+            amount_money: {amount: amount_to_refund, currency: (currency || "usd").to_s.upcase}
+          )
+        end
+
+        self.class.sync(processor_id, pay_customer: customer)
+      end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :pay_square_charge, Pay::Square::Charge

data/lib/pay/square/customer.rb

@@ -0,0 +1,79 @@
+module Pay
+  module Square
+    class Customer < Pay::Customer
+      has_many :charges, dependent: :destroy, class_name: "Pay::Square::Charge"
+      has_many :payment_methods, dependent: :destroy, class_name: "Pay::Square::PaymentMethod"
+      has_one :default_payment_method, -> { where(default: true) }, class_name: "Pay::Square::PaymentMethod"
+
+      # Override this in your Pay::Square::Customer (or via ActiveSupport.on_load
+      # :pay_square_customer) to send more fields to Square when creating the customer.
+      def api_record_attributes
+        {email_address: email, given_name: customer_name}.compact
+      end
+
+      def api_record
+        if processor_id?
+          Pay::Square.with_client(self) { |client| client.customers.get(customer_id: processor_id) }.customer
+        else
+          result = Pay::Square.with_client(self) { |client| client.customers.create(**api_record_attributes) }.customer
+          update!(processor_id: result.id)
+          result
+        end
+      end
+
+      # Pass a stable idempotency_key (e.g. keyed on the order) to make app-level resubmits
+      # dedupe; otherwise a generated key covers only this call and its 401 retry.
+      def charge(amount, options = {})
+        options = options.dup
+        idempotency_key = options.delete(:idempotency_key) || SecureRandom.uuid
+        currency = (options.delete(:currency) || "usd").to_s.upcase
+        source_id = options.delete(:source_id) || options.delete(:payment_method_id) || default_payment_method&.processor_id
+        raise Pay::Square::Error, "No source_id or default payment method for Square charge" if source_id.blank?
+
+        params = {
+          idempotency_key: idempotency_key,
+          source_id: source_id,
+          amount_money: {amount: amount, currency: currency},
+          customer_id: processor_id || api_record.id
+        }
+        if (app_fee = options.delete(:application_fee_amount) || options.delete(:app_fee_amount))
+          params[:app_fee_money] = {amount: app_fee, currency: currency}
+        end
+        params.merge!(options)
+
+        payment = Pay::Square.with_client(self) { |client| client.payments.create(**params) }.payment
+        Pay::Square::Charge.sync(payment.id, object: payment, pay_customer: self)
+      end
+
+      # source_id is a single-use nonce minted client-side by Square's Web Payments SDK.
+      def add_payment_method(source_id, default: false)
+        api_record unless processor_id?
+        idempotency_key = SecureRandom.uuid
+
+        card = Pay::Square.with_client(self) do |client|
+          client.cards.create(idempotency_key: idempotency_key, source_id: source_id, card: {customer_id: processor_id})
+        end.card
+
+        save_payment_method(card, default: default)
+      end
+
+      def update_payment_method(source_id)
+        add_payment_method(source_id, default: true)
+      end
+
+      def save_payment_method(card, default:)
+        pay_payment_method = payment_methods.where(processor_id: card.id).first_or_initialize
+
+        attributes = Pay::Square::PaymentMethod.extract_attributes(card).merge(default: default, square_account: square_account)
+
+        payment_methods.where.not(id: pay_payment_method.id).update_all(default: false) if default
+        pay_payment_method.update!(attributes)
+
+        reload_default_payment_method
+        pay_payment_method
+      end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :pay_square_customer, Pay::Square::Customer

data/lib/pay/square/engine.rb

@@ -0,0 +1,30 @@
+require "rails/engine"
+
+module Pay
+  module Square
+    class Engine < ::Rails::Engine
+      engine_name "pay_square"
+
+      initializer "pay_square.processors" do |app|
+        if Pay.automount_routes
+          app.routes.append do
+            mount Pay::Square::Engine, at: Pay.routes_path
+          end
+        end
+
+        ActiveSupport.on_load(:active_record) do
+          include Pay::Attributes
+        end
+      end
+
+      # Subscribe webhooks before app initializers, matching Pay's own ordering.
+      config.before_initialize do
+        Pay::Square.configure_webhooks if Pay::Square.enabled?
+      end
+
+      config.to_prepare do
+        Pay::Square.setup if Pay::Square.enabled?
+      end
+    end
+  end
+end

data/lib/pay/square/payment_method.rb

@@ -0,0 +1,37 @@
+module Pay
+  module Square
+    class PaymentMethod < Pay::PaymentMethod
+      # Pass `object` (the Square card) when you have it; otherwise it is re-fetched.
+      def self.sync(card_id, object: nil, pay_customer: nil, try: 0, retries: 1)
+        object ||= Pay::Square.with_client(pay_customer) { |client| client.cards.get(card_id: card_id) }.card
+        return if object.nil?
+
+        pay_customer ||= Pay::Customer.find_by(processor: :square, processor_id: object.customer_id)
+        return if pay_customer.nil?
+
+        pay_payment_method = pay_customer.payment_methods.where(processor_id: object.id).first_or_initialize
+        pay_payment_method.update!(extract_attributes(object).merge(square_account: pay_customer.square_account))
+        pay_payment_method
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique
+        if try >= retries
+          raise
+        else
+          sleep 0.15**(try + 1)
+          sync(card_id, object: object, pay_customer: pay_customer, try: try + 1, retries: retries)
+        end
+      end
+
+      def self.extract_attributes(card)
+        {
+          payment_method_type: "card",
+          brand: card.card_brand,
+          last4: card.last_4.to_s,
+          exp_month: card.exp_month.to_s,
+          exp_year: card.exp_year.to_s
+        }
+      end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :pay_square_payment_method, Pay::Square::PaymentMethod

data/lib/pay/square/version.rb

@@ -0,0 +1,5 @@
+module Pay
+  module Square
+    VERSION = "0.1.0.rc1"
+  end
+end

data/lib/pay/square/webhooks/card.rb

@@ -0,0 +1,22 @@
+module Pay
+  module Square
+    module Webhooks
+      class Card
+        def call(event)
+          event = Pay::Square.construct_from_webhook_event(event)
+          object = event.data&.object&.card
+          return unless object&.id
+
+          pay_customer = object.customer_id.present? ? Pay::Customer.find_by(processor: :square, processor_id: object.customer_id) : nil
+          return unless pay_customer
+
+          if event.type.to_s == "card.disabled"
+            Pay::PaymentMethod.find_by_processor_and_id(:square, object.id)&.destroy
+          else
+            Pay::Square::PaymentMethod.sync(object.id, pay_customer: pay_customer)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pay/square/webhooks/customer.rb

@@ -0,0 +1,20 @@
+module Pay
+  module Square
+    module Webhooks
+      class Customer
+        def call(event)
+          event = Pay::Square.construct_from_webhook_event(event)
+          object = event.data&.object&.customer
+          return unless object&.id
+
+          pay_customer = Pay::Customer.find_by(processor: :square, processor_id: object.id)
+          return unless pay_customer
+
+          if event.type.to_s == "customer.deleted"
+            pay_customer.update(deleted_at: Time.current) if pay_customer.respond_to?(:deleted_at)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pay/square/webhooks/payment.rb

@@ -0,0 +1,22 @@
+module Pay
+  module Square
+    module Webhooks
+      class Payment
+        def call(event)
+          event = Pay::Square.construct_from_webhook_event(event)
+          object = event.data&.object&.payment
+          return unless object&.id
+
+          pay_customer = object.customer_id.present? ? Pay::Customer.find_by(processor: :square, processor_id: object.customer_id) : nil
+          return unless pay_customer
+
+          pay_charge = Pay::Square::Charge.sync(object.id, pay_customer: pay_customer)
+
+          if pay_charge && Pay.send_email?(:receipt, pay_charge)
+            Pay.mailer.with(pay_customer: pay_charge.customer, pay_charge: pay_charge).receipt.deliver_later
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pay/square/webhooks/refund.rb

@@ -0,0 +1,23 @@
+module Pay
+  module Square
+    module Webhooks
+      class Refund
+        def call(event)
+          event = Pay::Square.construct_from_webhook_event(event)
+          object = event.data&.object&.refund
+          return unless object&.payment_id
+
+          pay_charge = Pay::Charge.find_by(processor_id: object.payment_id)
+          pay_customer = pay_charge&.customer || ((object.respond_to?(:customer_id) && object.customer_id.present?) ? Pay::Customer.find_by(processor: :square, processor_id: object.customer_id) : nil)
+          return unless pay_customer
+
+          pay_charge = Pay::Square::Charge.sync(object.payment_id, pay_customer: pay_customer)
+
+          if pay_charge && Pay.send_email?(:refund, pay_charge)
+            Pay.mailer.with(pay_customer: pay_charge.customer, pay_charge: pay_charge).refund.deliver_later
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pay/square.rb

@@ -0,0 +1,129 @@
+require "pay"
+# square.rb is app-provided (see gemspec); intentionally not required here.
+require "pay/square/version"
+require "pay/square/engine"
+require "pay/square/attributes"
+
+module Pay
+  module Square
+    # Unlike Stripe Connect (one platform key + a stripe_account header), Square issues a
+    # distinct OAuth access token per merchant, so the processor builds a Square::Client
+    # per operation from a token supplied by access_token_provider.
+    class Error < Pay::Error
+    end
+
+    autoload :Customer, "pay/square/customer"
+    autoload :Charge, "pay/square/charge"
+    autoload :PaymentMethod, "pay/square/payment_method"
+
+    module Webhooks
+      autoload :Payment, "pay/square/webhooks/payment"
+      autoload :Refund, "pay/square/webhooks/refund"
+      autoload :Card, "pay/square/webhooks/card"
+      autoload :Customer, "pay/square/webhooks/customer"
+    end
+
+    extend Pay::Env
+
+    REQUIRED_VERSION = "~> 44"
+
+    # A callable accepting (pay_customer, force_refresh = false) that returns a fresh
+    # per-merchant OAuth access token. force_refresh is set true on the retry after a 401.
+    mattr_accessor :access_token_provider, default: nil
+
+    def self.enabled?
+      return false unless defined?(::Square)
+
+      # square.rb does not autoload Square::VERSION on `require "square"`.
+      current = ::Gem.loaded_specs["square.rb"]&.version&.to_s
+      return true if current.nil?
+      Pay::Engine.version_matches?(required: REQUIRED_VERSION, current: current) || (raise "[Pay::Square] square.rb gem must be version #{REQUIRED_VERSION}")
+    end
+
+    # No global API key: Square authenticates per-merchant via access_token_provider.
+    def self.setup
+    end
+
+    def self.environment
+      find_value_by_name(:square, :environment).presence || "production"
+    end
+
+    def self.base_url
+      (environment.to_s == "sandbox") ? ::Square::Environment::SANDBOX : ::Square::Environment::PRODUCTION
+    end
+
+    def self.signing_secret
+      find_value_by_name(:square, :signing_secret)
+    end
+
+    # Square's HMAC covers (notification_url + body), so this must match the URL registered
+    # with Square; behind a proxy request.original_url may not.
+    def self.webhook_notification_url
+      find_value_by_name(:square, :webhook_notification_url)
+    end
+
+    def self.access_token(pay_customer, force_refresh: false)
+      unless access_token_provider.respond_to?(:call)
+        raise Pay::Square::Error, "Pay::Square.access_token_provider is not configured. Set it to a callable that returns a fresh Square OAuth access token for a Pay::Customer."
+      end
+
+      token = if access_token_provider.arity == 1 || access_token_provider.arity.zero?
+        access_token_provider.call(pay_customer)
+      else
+        access_token_provider.call(pay_customer, force_refresh)
+      end
+
+      raise Pay::Square::Error, "Pay::Square.access_token_provider returned a blank token for pay_customer #{pay_customer&.id}" if token.blank?
+      token
+    end
+
+    def self.client(pay_customer, force_refresh: false)
+      ::Square::Client.new(base_url: base_url, token: access_token(pay_customer, force_refresh: force_refresh))
+    end
+
+    # Retries ONCE with a force-refreshed token on a 401 and maps Square errors to
+    # Pay::Square::Error. Callers MUST build any idempotency_key outside this block so the
+    # retry reuses the same key and cannot double-charge.
+    def self.with_client(pay_customer)
+      attempts = 0
+      begin
+        attempts += 1
+        yield client(pay_customer, force_refresh: attempts > 1)
+      rescue ::Square::Errors::UnauthorizedError => e
+        if attempts < 2
+          Rails.logger.info { "[Pay::Square] access token rejected (401) for pay_customer #{pay_customer&.id}; forcing refresh and retrying" }
+          retry
+        end
+        raise Pay::Square::Error, e
+      rescue ::Square::Errors::ApiError => e
+        raise Pay::Square::Error, e
+      end
+    end
+
+    def self.construct_from_webhook_event(event)
+      case event
+      when Hash
+        ActiveSupport::InheritableOptions.new(event.map { |key, value| [key.to_sym, construct_from_webhook_event(value)] }.to_h)
+      when Array
+        event.map { |value| construct_from_webhook_event(value) }
+      else
+        event
+      end
+    end
+
+    def self.configure_webhooks
+      Pay::Webhooks.configure do |events|
+        events.subscribe "square.payment.created", Pay::Square::Webhooks::Payment.new
+        events.subscribe "square.payment.updated", Pay::Square::Webhooks::Payment.new
+        events.subscribe "square.refund.created", Pay::Square::Webhooks::Refund.new
+        events.subscribe "square.refund.updated", Pay::Square::Webhooks::Refund.new
+        events.subscribe "square.card.created", Pay::Square::Webhooks::Card.new
+        events.subscribe "square.card.updated", Pay::Square::Webhooks::Card.new
+        events.subscribe "square.card.disabled", Pay::Square::Webhooks::Card.new
+        events.subscribe "square.customer.created", Pay::Square::Webhooks::Customer.new
+        events.subscribe "square.customer.updated", Pay::Square::Webhooks::Customer.new
+        events.subscribe "square.customer.deleted", Pay::Square::Webhooks::Customer.new
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: pay-square
+version: !ruby/object:Gem::Version
+  version: 0.1.0.rc1
+platform: ruby
+authors:
+- Willard Moore
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pay
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '11.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '11.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '13'
+description: Adds a Square payment processor to Pay. Charge on a merchant's own connected
+  Square account (per-merchant OAuth), with card-on-file, refunds, application fees,
+  and webhooks.
+email:
+- willardgmoore@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/pay/webhooks/square_controller.rb
+- config/routes.rb
+- db/migrate/20250901000001_add_square_account_to_pay_models.rb
+- lib/pay/square.rb
+- lib/pay/square/attributes.rb
+- lib/pay/square/charge.rb
+- lib/pay/square/customer.rb
+- lib/pay/square/engine.rb
+- lib/pay/square/payment_method.rb
+- lib/pay/square/version.rb
+- lib/pay/square/webhooks/card.rb
+- lib/pay/square/webhooks/customer.rb
+- lib/pay/square/webhooks/payment.rb
+- lib/pay/square/webhooks/refund.rb
+homepage: https://github.com/Willardgmoore/pay-square
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Willardgmoore/pay-square
+  changelog_uri: https://github.com/Willardgmoore/pay-square/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Square payment processor for the Pay gem
+test_files: []