TypeScript wrapper for Square API with webhook support for Node.js backends
npm install @bates-solutions/squareup
The modern TypeScript SDK for Square payments
Build payment backends with type-safe APIs, fluent builders, and webhook support.
---
Stop wrestling with Square's low-level APIs. squareup gives you a simplified client API and fluent builders that make payment integration straightforward. Process payments, manage orders, handle webhooks—all with full TypeScript support and zero boilerplate.
- Simplified APIs - Less boilerplate, more productivity
- Type-Safe - Full TypeScript support with strict types
- Fluent Builders - Chainable order and payment construction
- Webhook Support - Signature verification and middleware for Express/Next.js
- Service Classes - Payments, Orders, Customers, Catalog, Inventory, Subscriptions, Invoices, Loyalty
| Dependency | Version |
| ---------- | ------- |
| Square SDK | ^43.0.0 |
| Node.js | 22+ |
| TypeScript | 5.0+ |
``bash`
npm install @bates-solutions/squareup square
`typescript
import { createSquareClient } from '@bates-solutions/squareup';
const client = createSquareClient({
accessToken: process.env.SQUARE_ACCESS_TOKEN!,
environment: 'sandbox',
});
// Process a payment
const payment = await client.payments.create({
sourceId: 'cnon:card-nonce',
amount: 1000, // $10.00
currency: 'USD',
});
// Create an order with the fluent builder
const order = await client.orders.create(
client.orders
.builder()
.addItem({ name: 'Coffee', quantity: 2, amount: 450 })
.addItem({ name: 'Muffin', quantity: 1, amount: 350 })
.build()
);
// Manage customers
const customer = await client.customers.create({
givenName: 'John',
familyName: 'Doe',
emailAddress: 'john@example.com',
});
`
`typescript
import express from 'express';
import { createWebhookHandler, rawBodyMiddleware } from '@bates-solutions/squareup/server';
const app = express();
// Use raw body middleware before JSON parsing for webhook routes
app.use('/webhooks/square', rawBodyMiddleware);
app.use(express.json());
const webhookHandler = createWebhookHandler({
signatureKey: process.env.SQUARE_WEBHOOK_SIGNATURE_KEY!,
});
app.post('/webhooks/square', (req, res) => {
const event = webhookHandler.verifyAndParse(req);
switch (event.type) {
case 'payment.completed':
console.log('Payment completed:', event.data);
break;
case 'order.created':
console.log('Order created:', event.data);
break;
}
res.sendStatus(200);
});
`
`typescript
// app/api/webhooks/square/route.ts
import { createWebhookHandler } from '@bates-solutions/squareup/server';
const webhookHandler = createWebhookHandler({
signatureKey: process.env.SQUARE_WEBHOOK_SIGNATURE_KEY!,
});
export async function POST(request: Request) {
const body = await request.text();
const signature = request.headers.get('x-square-hmacsha256-signature')!;
const event = webhookHandler.verifyAndParse(body, signature);
// Handle the event
console.log('Received event:', event.type);
return new Response('OK', { status: 200 });
}
`
| Service | Description |
| --------------- | ------------------------------------ |
| payments | Process and manage payments |orders
| | Create and manage orders |customers
| | Customer management |catalog
| | Product catalog operations |inventory
| | Inventory tracking |subscriptions
| | Subscription management |invoices
| | Invoice operations |loyalty
| | Loyalty program management |
`typescript
import { toCents, fromCents, formatMoney } from '@bates-solutions/squareup';
toCents(10.99); // 1099
fromCents(1099); // 10.99
formatMoney(1099, 'USD'); // "$10.99"
``
We welcome contributions! Please see our Contributing Guide for details.
MIT - see LICENSE for details.