💳 Pay::Square — Square for the Pay gem

A Square payment processor for Pay — the payments engine for Ruby on 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.

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

Braintree and Paddle are being split out for maintainability alone. Square is a different case: here it is used for marketplace payments — 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.

• Ruby >= 3.1.0
• Pay 11.x or 12.x (verified against 11.7.2 and 12.3.0)
• square.rb ~> 44

• Installation — Gemfile, pre-releases, and the migration
• Configuration — the per-merchant token resolver and credentials
• Usage — charges, card-on-file, refunds, and per-merchant isolation
• Webhooks — endpoint, signature verification, and handled events
• Versioning & releasing — SemVer, tags, pre-releases, and publishing
• Contributing — dev setup, running the tests, and opening issues

Bug reports, feature ideas, and pull requests are welcome. See CONTRIBUTING.md to get started.

pay-square on RubyGems · Changelog

The RubyGems and Pay logos are trademarks of their respective projects, used here to link to those projects, not to imply endorsement.

MIT.