Square Sandbox Testing

beginner

Development setup for Square payments.

Overview

Node.js is a JavaScript runtime environment built on Chrome's V8 JavaScript engine that enables server-side JavaScript execution. Originally created by Ryan Dahl in 2009, Node.js revolutionized web development by allowing developers to use JavaScript for both frontend and backend development, eliminating the need to switch between programming languages. Its event-driven, non-blocking I/O model makes it particularly well-suited for building scalable network applications and APIs that handle concurrent requests efficiently. This Square Sandbox Testing configuration combines Node.js with Square's payment processing APIs to create a complete development environment for e-commerce applications. The setup leverages Node.js's excellent HTTP handling capabilities and rich ecosystem of packages to integrate with Square's payment infrastructure, while the sandbox environment ensures that all payment testing occurs in a safe, isolated environment without processing real transactions or charges. Developers building e-commerce platforms, payment integrators, and fintech startups will find this stack invaluable for rapid prototyping and testing payment workflows. The combination allows teams to develop and validate payment processing logic, test webhook handling, and simulate various payment scenarios without the complexity and risk of working directly with production payment systems.

Key Features

Square SDK integration with Node.js for complete payment API access
Sandbox environment isolation preventing accidental real transaction processing
Built-in webhook testing capabilities through Square's developer dashboard
Test card validation with predefined card numbers and CVV combinations
Real-time payment event simulation without financial commitments
Node.js event-driven architecture optimized for handling payment callbacks
Square CLI integration support for advanced testing scenarios
Alpine Linux base image reducing container size and attack surface

Common Use Cases

1E-commerce platform development with integrated Square payment processing
2Point-of-sale application testing and payment flow validation
3Webhook endpoint development for payment status notifications
4Payment integration testing for mobile applications and web stores
5Fintech product prototyping with real payment API interactions
6Developer training environments for Square payment integration
7Continuous integration testing pipelines for payment-enabled applications

Prerequisites

Square Developer Account with sandbox access and API credentials
Docker and Docker Compose installed with at least 512MB available memory
Port 3000 available on the host system for application access
Basic JavaScript and Node.js development knowledge
Understanding of payment processing concepts and webhook handling
Square Access Token generated from the developer dashboard

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  square-app: 
3    image: node:20-alpine
4    container_name: square-app
5    restart: unless-stopped
6    working_dir: /app
7    command: npm start
8    environment: 
9      SQUARE_ACCESS_TOKEN: ${SQUARE_ACCESS_TOKEN}
10      SQUARE_ENVIRONMENT: sandbox
11    volumes: 
12      - ./app:/app
13    ports: 
14      - "3000:3000"

.env Template

.env

1SQUARE_ACCESS_TOKEN=your-sandbox-token

Usage Notes

1Docs: https://developer.squareup.com/docs/
2App at http://localhost:3000, get sandbox token from Square dashboard
3Test card: 4532 0123 4567 8901, any CVV, future expiry
4Use Square SDK: npm install square
5Sandbox mode: all API calls work but no real transactions
6Test webhook events via Square dashboard or CLI

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  square-app:
5    image: node:20-alpine
6    container_name: square-app
7    restart: unless-stopped
8    working_dir: /app
9    command: npm start
10    environment:
11      SQUARE_ACCESS_TOKEN: ${SQUARE_ACCESS_TOKEN}
12      SQUARE_ENVIRONMENT: sandbox
13    volumes:
14      - ./app:/app
15    ports:
16      - "3000:3000"
17EOF
18
19# 2. Create the .env file
20cat > .env << 'EOF'
21SQUARE_ACCESS_TOKEN=your-sandbox-token
22EOF
23
24# 3. Start the services
25docker compose up -d
26
27# 4. View logs
28docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/square-sandbox/run | bash

Troubleshooting

Error: SQUARE_ACCESS_TOKEN not found: Ensure environment variable is set in .env file with valid sandbox token from Square dashboard
Connection refused on port 3000: Check if another service is using port 3000 or modify the port mapping in docker-compose.yml
npm start command fails: Verify package.json exists in ./app directory with proper start script and dependencies
Square API returns 401 Unauthorized: Confirm access token is valid and matches the sandbox environment setting
Payment test fails with invalid card: Use Square's test card 4532 0123 4567 8901 with any 3-digit CVV and future expiration date
Module 'square' not found: Run 'npm install square' in the app directory to install the Square Node.js SDK

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

node

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download