Module and release scope
This guide covers Square Payment Links 1.0.0, Extension API 1, from the reviewed product source. Its declared core range is 1.3.6–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.
Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.
Exact connection fields
These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.
| Key / label | Type | Required | Default / guidance |
|---|---|---|---|
mode — Environment |
select | Yes | Default: "sandbox" Choices: sandbox = Sandbox, live = Live |
access_token — Access token |
secret | Yes | Use a token belonging to the configured seller and environment. |
merchant_id — Seller merchant ID |
text | Yes | Use the account-specific value described below. |
location_id — Location ID |
text | Yes | Use the account-specific value described below. |
currency — Location invoice currency |
select | Yes | Default: "USD" Choices: AUD = AUD, CAD = CAD, EUR = EUR, GBP = GBP, USD = USD |
webhook_url — Registered webhook URL |
text | Yes | Paste the exact HTTPS connection webhook URL shown on this page; use the same URL in Square Developer Console. |
webhook_signature_key — Webhook signature key |
secret | Yes | Subscribe to payment.created and payment.updated using this application signature key. |
Square-hosted one-off invoice checkout using API version 2026-09-16. Requires EmailaBiller 1.3.6 or later. Installed disabled, without a merchant account or credentials.
Configure
- Create a Square Developer application and a Sandbox seller/location. Use that application's matching Sandbox access token, seller merchant ID and location ID.
- The access token must allow MERCHANT_PROFILE_READ, ORDERS_READ, ORDERS_WRITE, PAYMENTS_READ and PAYMENTS_WRITE. These permit location verification, hosted order creation and payment retrieval; this module never submits a card charge directly.
- Choose the actual location currency: AUD, CAD, EUR, GBP or USD. The read-only location test must return that exact currency and seller. JPY is excluded because this application currently uses two decimal places. There is no invoice currency conversion.
- In Developer Console → Webhooks, create a subscription for payment.created and payment.updated. Copy this connection's exact HTTPS webhook URL into Square and into the module's registered webhook URL field, including its path. Copy the subscription's signature key. URL spelling matters because it participates in signature verification.
- Save and Test. Testing only reads the active location and checks the seller/currency. Complete a sandbox checkout and webhook delivery before enabling the connection.
- For production, use Live mode and the production seller token, location, merchant ID and webhook subscription. Re-test and enable explicitly.
Hosted flow and verification
The module creates one order and a payment link using the checkout UUID as its idempotency key. The customer enters payment details on Square. Tipping and shipping collection are disabled for the invoice payment.
Returns use the owned checkout's stored order ID. A webhook must pass Square's HMAC-SHA256 check over the exact registered URL and raw body, and match the seller. Authenticated Orders and Payments reads must agree on the invoice reference/metadata, original amount, currency, location, single tender and completed payment. Refunds, tips, authorization-only states, cash/external payment records, duplicate tenders and unsigned claims do not produce paid evidence. The core additionally validates invoice ownership and amount, and deduplicates stable payment IDs.
No subscriptions, card vault, automatic refunds or split-tender collection are implemented. Checkout creation is never automatically retried after a timeout.
Provider documentation
- Create payment link and required permissions
- Sandbox hosted link examples
- Order-based hosted checkout
- Location authentication and currency
- Retrieve payment and completed status
- Order reference, metadata and tenders
- Webhook signature verification
HTTP failures show safe status/setup guidance without exposing tokens or provider response bodies.