💳 Vendure Square Payment Plugin

Official Square payment integration for Vendure e-commerce platform

Process real payments through Square with full PCI compliance, automatic tokenization, and support for authorization, settlement, and refunds.

✨ Features

• 💳 Full Payment Lifecycle - Authorization, settlement, and refunds
• 🔒 PCI Compliant - Card data never touches your server
• 🌍 Multi-Currency Support - All Square-supported currencies
• 🧪 Sandbox Testing - Complete test environment with Square test cards
• 📊 Transaction Metadata - Full Square transaction details stored
• 🔄 Idempotent Operations - Prevents duplicate charges
• ⚡ TypeScript - Full type safety with TypeScript definitions
• 🛡️ Error Handling - Comprehensive error states and messages

📦 Installation

npm install vendure-plugin-square square

Peer Dependencies:

• @vendure/core: ^3.0.0
• square: ^43.0.0

🚀 Quick Start

1. Get Square Credentials

1. Create a Square Developer account at https://developer.squareup.com
2. Create a new application
3. Get your credentials:
   • Application ID (for Web Payments SDK)
   • Access Token (for backend API)
   • Location ID (from your Square locations)

2. Configure Backend

Add to your vendure-config.ts:

import { SquarePlugin, squarePaymentHandler } from 'vendure-plugin-square';

export const config: VendureConfig = {
  // ... other config
  paymentOptions: {
    paymentMethodHandlers: [squarePaymentHandler],
  },
  plugins: [
    SquarePlugin.init({
      accessToken: process.env.SQUARE_ACCESS_TOKEN!,
      environment: process.env.SQUARE_ENVIRONMENT as 'sandbox' | 'production',
      locationId: process.env.SQUARE_LOCATION_ID!,
    }),
    // ... other plugins
  ],
};

3. Environment Variables

Add to your .env:

# Square Configuration
SQUARE_ACCESS_TOKEN=your_square_access_token
SQUARE_ENVIRONMENT=sandbox  # or 'production'
SQUARE_LOCATION_ID=your_location_id

4. Create Payment Method in Admin

1. Login to Vendure Admin UI
2. Go to Settings → Payment methods
3. Click "Create new payment method"
4. Configure:
   • Code: square-payment
   • Handler: Select "Square Payment"
   • Enabled: ON
5. Save

🎨 Frontend Integration

Install Square Web Payments SDK

Add the Square SDK to your storefront:

import { useEffect, useState } from 'react';

// Load Square SDK
useEffect(() => {
  const script = document.createElement('script');
  script.src = 'https://sandbox.web.squarecdn.com/v1/square.js'; // or production URL
  script.async = true;
  document.body.appendChild(script);
}, []);

Initialize Payment Form

const payments = Square.payments(
  process.env.NEXT_PUBLIC_SQUARE_APPLICATION_ID,
  process.env.NEXT_PUBLIC_SQUARE_LOCATION_ID
);

const card = await payments.card();
await card.attach('#card-container');

// Tokenize card when submitting
const result = await card.tokenize();
const token = result.token;

Submit Payment

import { addPaymentToOrder } from '@vendure/core';

const paymentResult = await addPaymentToOrder({
  method: 'square-payment',
  metadata: {
    sourceId: token, // Square payment token
  },
});

🔄 Payment Flow

Authorization Flow (Two-Step)

By default, payments are authorized but not captured:

1. Customer submits payment
2. Square authorizes payment (reserves funds)
3. Order state: PaymentAuthorized
4. Admin settles payment in Vendure Admin
5. Square captures funds
6. Order state: PaymentSettled

Benefits:

• Verify inventory before capturing
• Cancel without refunding
• Better fraud protection

Auto-Settlement (One-Step)

To automatically capture payments, modify the handler:

// In square-payment-handler.ts, line ~92
autocomplete: true,  // Change from false to true

🧪 Testing

Sandbox Mode

Use Square's test card numbers:

| Card Number | Scenario | |-------------|----------| | 4111 1111 1111 1111 | Successful charge | | 4000 0000 0000 0002 | Card declined | | 4000 0000 0000 0341 | Insufficient funds |

Test Card Details:

• CVV: Any 3 digits (e.g., 111)
• Expiration: Any future date (e.g., 12/25)
• ZIP Code: Any 5 digits (e.g., 90210)

More test values: https://developer.squareup.com/docs/devtools/sandbox/payments

🛠️ API Reference

SquarePlugin.init(options)

Initialize the plugin with Square credentials.

Parameters:

| Option | Type | Description | |--------|------|-------------| | accessToken | string | Square API access token (required) | | environment | 'sandbox' \| 'production' | Square environment (required) | | locationId | string | Square location ID (required) |

Example:

SquarePlugin.init({
  accessToken: process.env.SQUARE_ACCESS_TOKEN!,
  environment: 'sandbox',
  locationId: process.env.SQUARE_LOCATION_ID!,
})

squarePaymentHandler

Payment method handler with code 'square-payment'.

Methods:

• createPayment: Authorizes payment with Square
• settlePayment: Captures authorized payment
• createRefund: Processes full or partial refunds

🔐 Security

PCI Compliance

• ✅ Card data handled entirely by Square
• ✅ Single-use payment tokens
• ✅ No sensitive data stored on your server
• ✅ HTTPS required for production

Best Practices

• Store access tokens in environment variables
• Never commit credentials to version control
• Use sandbox for development/testing
• Enable HTTPS on production domains
• Regularly rotate access tokens

🐛 Troubleshooting

"Payment method not found"

Solution: Create payment method in Vendure Admin with handler code 'square-payment'

"Square SDK not loaded"

Solution: Ensure Square Web Payments SDK script is loaded before initializing payment form

"Missing Square payment token"

Solution: Card tokenization failed - check card details or Square SDK initialization

"Authentication failed"

Solution: Verify Square access token and environment (sandbox vs production)

📚 Documentation

Square Developer Resources

• Square Developer Portal
• Payments API Guide
• Web Payments SDK
• Testing Guide

Vendure Resources

• Vendure Docs
• Payment Integration Guide
• Plugin Development

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

git clone https://github.com/yourusername/vendure-plugin-square.git
cd vendure-plugin-square
npm install
npm run build

📄 License

MIT License - see LICENSE file for details

💪 Credits

Built with ❤️ for the Vendure community

Special Thanks:

• Vendure team for the amazing e-commerce framework
• Square for their robust payment APIs
• The open-source community

🚀 Changelog

v1.0.0 (2025-09-30)

Initial Release

• ✅ Complete Square payment integration
• ✅ Authorization and settlement support
• ✅ Refund processing
• ✅ PCI-compliant tokenization
• ✅ Sandbox and production environments
• ✅ Full TypeScript support
• ✅ Comprehensive error handling

Questions or issues? Open an issue on GitHub

Want to contribute? PRs are always welcome! 🎉