Square payment integration plugin for Vendure e-commerce. Supports payment authorization, settlement, and refunds with PCI-compliant card tokenization.
npm install @dylanmurzello/vendure-plugin-squareOfficial 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.
---
- 💳 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
---
``bash`
npm install vendure-plugin-square square
Peer Dependencies:
- @vendure/core: ^3.0.0square
- : ^43.0.0
---
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)
Add to your vendure-config.ts:
`typescript
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
],
};
`
Add to your .env:
`bash`Square Configuration
SQUARE_ACCESS_TOKEN=your_square_access_token
SQUARE_ENVIRONMENT=sandbox # or 'production'
SQUARE_LOCATION_ID=your_location_id
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
---
Add the Square SDK to your storefront:
`typescript
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);
}, []);
`
`typescript
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;
`
`typescript
import { addPaymentToOrder } from '@vendure/core';
const paymentResult = await addPaymentToOrder({
method: 'square-payment',
metadata: {
sourceId: token, // Square payment token
},
});
`
---
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
To automatically capture payments, modify the handler:
`typescript`
// In square-payment-handler.ts, line ~92
autocomplete: true, // Change from false to true
---
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)12/25
- Expiration: Any future date (e.g., )90210
- ZIP Code: Any 5 digits (e.g., )
More test values: https://developer.squareup.com/docs/devtools/sandbox/payments
---
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:
`typescript`
SquarePlugin.init({
accessToken: process.env.SQUARE_ACCESS_TOKEN!,
environment: 'sandbox',
locationId: process.env.SQUARE_LOCATION_ID!,
})
Payment method handler with code 'square-payment'.
Methods:
- createPayment: Authorizes payment with Square
- settlePayment: Captures authorized payment
- createRefund: Processes full or partial refunds
---
- ✅ Card data handled entirely by Square
- ✅ Single-use payment tokens
- ✅ No sensitive data stored on your server
- ✅ HTTPS required for production
- 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
---
Solution: Create payment method in Vendure Admin with handler code 'square-payment'
Solution: Ensure Square Web Payments SDK script is loaded before initializing payment form
Solution: Card tokenization failed - check card details or Square SDK initialization
Solution: Verify Square access token and environment (sandbox vs production)
---
- Square Developer Portal
- Payments API Guide
- Web Payments SDK
- Testing Guide
- Vendure Docs
- Payment Integration Guide
- Plugin Development
---
Contributions are welcome! Please feel free to submit a Pull Request.
`bash``
git clone https://github.com/yourusername/vendure-plugin-square.git
cd vendure-plugin-square
npm install
npm run build
---
MIT License - see LICENSE file for details
---
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
---
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! 🎉