AbsoluteJS

@absolutejs/commerce-square

@absolutejs/commerce-squarev0.1.0-beta.1betaCommerce & Growth

Square Terminal adapter for @absolutejs/commerce — take a card at the counter on the shop's own hardware

#Installation

BASH
bun add @absolutejs/commerce-square

#Capabilities

Overview

Square Terminal as a TerminalProvider for @absolutejs/commerce.

Online checkout and the counter are different shapes. Online, the browser goes to the provider and comes back. At the counter, the customer taps a card on a piece of hardware the shop owns, and the till waits for it. This adapter is that second shape: list the paired Terminals, send an amount to one, watch the checkout, cancel it, and verify the webhook Square sends when it changes.

Money is integer cents, like everywhere else in commerce.

Show 7 more

No SDK. Four REST calls and an HMAC; fetchImpl is injectable, so the

whole flow is testable without a network.

Webhooks are refused, not trusted, without a signature key. Square signs

the notification URL followed by the raw body — both must match.

A cancel with a reason (timed out, buyer walked away) reads as failed

rather than canceled, because those are different things to a shop.

Pairing a Terminal happens on the device itself. The access token needs PAYMENTS_WRITE and DEVICE_CREDENTIAL_MANAGEMENT.

Outcomes

What you can build

Build on the supported package contract

Use @absolutejs/commerce-square through its supported public entry points.

Hardening checklist

Production guidance

Make every external boundary explicitPin the deployed @absolutejs/commerce-square version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.

Follow in order

Troubleshooting path

1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/commerce-square example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.

#@absolutejs/commerce-square quick start

Partial snippet

# @absolutejs/commerce-square

TS
import { createSquareTerminal } from "@absolutejs/commerce-square";

const terminal = createSquareTerminal({
  accessToken: process.env.SQUARE_ACCESS_TOKEN ?? "",
  environment: "sandbox",
  webhookSignatureKey: process.env.SQUARE_WEBHOOK_SIGNATURE_KEY,
  webhookUrl: "https://yourshop.com/api/square/webhook",
});

const devices = await terminal.listDevices();
const checkout = await terminal.startCheckout({
  amountCents: 4500,
  deviceId: devices[0].id,
  idempotencyKey: saleId,
  reference: "walk-in-88",
});
// …the customer taps; Square posts terminal.checkout.updated
const { checkout: done } = await terminal.verifyWebhook(body, signature);

#Public entry points

Supported entry points declared by this package manifest.

Package entry point declared in package.json.

@absolutejs/commerce-square@absolutejs/commerce-square/manifest@absolutejs/commerce-square/manifest.json

#Package commands

Scripts declared by this package manifest.

bun run buildrm -rf dist && bun build ./src/index.ts ./src/manifest.ts --root ./src --outdir dist --target bun --external @absolutejs/commerce --external '@absolutejs/commerce/*' --external @absolutejs/manifest --external @sinclair/typebox && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit
bun run check:packagebun run format && bun run typecheck && bun run test && bun run verify-package && bun run build
bun run formatprettier --write "./**/*.{js,ts,json,md}"
bun run testbun test
bun run typechecktsc --noEmit