$docker.recipes

Square Sandbox Testing

beginner

Development setup for Square payments.

[i]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

  • [1]E-commerce platform development with integrated Square payment processing
  • [2]Point-of-sale application testing and payment flow validation
  • [3]Webhook endpoint development for payment status notifications
  • [4]Payment integration testing for mobile applications and web stores
  • [5]Fintech product prototyping with real payment API interactions
  • [6]Developer training environments for Square payment integration
  • [7]Continuous 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
[!]

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

[$]docker-compose.yml

[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

[i]Usage Notes

  1. [1]Docs: https://developer.squareup.com/docs/
  2. [2]App at http://localhost:3000, get sandbox token from Square dashboard
  3. [3]Test card: 4532 0123 4567 8901, any CVV, future expiry
  4. [4]Use Square SDK: npm install square
  5. [5]Sandbox mode: all API calls work but no real transactions
  6. [6]Test 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...
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

## Tags

#square#payments#sandbox#testing

## Category

E-Commerce & Business

## Related