{"_id":"@dylanmurzello/vendure-plugin-square","name":"@dylanmurzello/vendure-plugin-square","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@dylanmurzello/vendure-plugin-square","version":"1.0.0","description":"Square payment integration plugin for Vendure e-commerce. Supports payment authorization, settlement, and refunds with PCI-compliant card tokenization.","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build","test":"echo \"Error: no test specified\" && exit 1"},"keywords":["vendure","vendure-plugin","square","payments","ecommerce","payment-gateway","square-payments","payment-processing"],"author":{"name":"Dylan Murzello","email":"dylanmurzello@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Dylanmurzello/vendure-plugin-square.git"},"bugs":{"url":"https://github.com/Dylanmurzello/vendure-plugin-square/issues"},"homepage":"https://github.com/Dylanmurzello/vendure-plugin-square#readme","peerDependencies":{"@vendure/core":"^3.0.0","square":"^43.0.0"},"devDependencies":{"@vendure/core":"^3.4.2","square":"^43.1.0","typescript":"^5.8.2"},"engines":{"node":">=18.0.0"},"_id":"@dylanmurzello/vendure-plugin-square@1.0.0","gitHead":"bb2960c72d62fd0970c29e4dc5ae231601f6231e","_nodeVersion":"24.8.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-vMLuPOXZkAQl+86vQ4jnACvZhGM0w+z0IJj0hf6l43l+LTRkgLp+XTFiwYZhDKSKWd8OZc7eWAeZxp4oJxfpbw==","shasum":"ecd2aa588a760d4c1cb5b70849d15a1f35b6dcf7","tarball":"https://registry.npmjs.org/@dylanmurzello/vendure-plugin-square/-/vendure-plugin-square-1.0.0.tgz","fileCount":12,"unpackedSize":28771,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHyj9uAh66Np9uGAo8UyULqbgDCkrzTFPuUMv37kGrxKAiEA2mvAX5J1BNtzXryWn94DvK7+MKSSYMjUkHjA6jBquK0="}]},"_npmUser":{"name":"dylanmurzello","email":"dylanmurzello@gmail.com"},"directories":{},"maintainers":[{"name":"dylanmurzello","email":"dylanmurzello@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vendure-plugin-square_1.0.0_1759272583159_0.35284697792766284"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-30T22:49:43.082Z","1.0.0":"2025-09-30T22:49:43.368Z","modified":"2025-09-30T22:49:43.677Z"},"maintainers":[{"name":"dylanmurzello","email":"dylanmurzello@gmail.com"}],"description":"Square payment integration plugin for Vendure e-commerce. Supports payment authorization, settlement, and refunds with PCI-compliant card tokenization.","homepage":"https://github.com/Dylanmurzello/vendure-plugin-square#readme","keywords":["vendure","vendure-plugin","square","payments","ecommerce","payment-gateway","square-payments","payment-processing"],"repository":{"type":"git","url":"git+https://github.com/Dylanmurzello/vendure-plugin-square.git"},"author":{"name":"Dylan Murzello","email":"dylanmurzello@gmail.com"},"bugs":{"url":"https://github.com/Dylanmurzello/vendure-plugin-square/issues"},"license":"MIT","readme":"# 💳 Vendure Square Payment Plugin\n\n**Official Square payment integration for Vendure e-commerce platform**\n\nProcess real payments through Square with full PCI compliance, automatic tokenization, and support for authorization, settlement, and refunds.\n\n[![npm version](https://img.shields.io/npm/v/vendure-plugin-square.svg)](https://www.npmjs.com/package/vendure-plugin-square)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n---\n\n## ✨ Features\n\n- 💳 **Full Payment Lifecycle** - Authorization, settlement, and refunds\n- 🔒 **PCI Compliant** - Card data never touches your server\n- 🌍 **Multi-Currency Support** - All Square-supported currencies\n- 🧪 **Sandbox Testing** - Complete test environment with Square test cards\n- 📊 **Transaction Metadata** - Full Square transaction details stored\n- 🔄 **Idempotent Operations** - Prevents duplicate charges\n- ⚡ **TypeScript** - Full type safety with TypeScript definitions\n- 🛡️ **Error Handling** - Comprehensive error states and messages\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install vendure-plugin-square square\n```\n\n**Peer Dependencies:**\n- `@vendure/core`: ^3.0.0\n- `square`: ^43.0.0\n\n---\n\n## 🚀 Quick Start\n\n### 1. Get Square Credentials\n\n1. Create a Square Developer account at https://developer.squareup.com\n2. Create a new application\n3. Get your credentials:\n   - **Application ID** (for Web Payments SDK)\n   - **Access Token** (for backend API)\n   - **Location ID** (from your Square locations)\n\n### 2. Configure Backend\n\nAdd to your `vendure-config.ts`:\n\n```typescript\nimport { SquarePlugin, squarePaymentHandler } from 'vendure-plugin-square';\n\nexport const config: VendureConfig = {\n  // ... other config\n  paymentOptions: {\n    paymentMethodHandlers: [squarePaymentHandler],\n  },\n  plugins: [\n    SquarePlugin.init({\n      accessToken: process.env.SQUARE_ACCESS_TOKEN!,\n      environment: process.env.SQUARE_ENVIRONMENT as 'sandbox' | 'production',\n      locationId: process.env.SQUARE_LOCATION_ID!,\n    }),\n    // ... other plugins\n  ],\n};\n```\n\n### 3. Environment Variables\n\nAdd to your `.env`:\n\n```bash\n# Square Configuration\nSQUARE_ACCESS_TOKEN=your_square_access_token\nSQUARE_ENVIRONMENT=sandbox  # or 'production'\nSQUARE_LOCATION_ID=your_location_id\n```\n\n### 4. Create Payment Method in Admin\n\n1. Login to Vendure Admin UI\n2. Go to **Settings → Payment methods**\n3. Click **\"Create new payment method\"**\n4. Configure:\n   - **Code:** `square-payment`\n   - **Handler:** Select \"Square Payment\"\n   - **Enabled:** ON\n5. Save\n\n---\n\n## 🎨 Frontend Integration\n\n### Install Square Web Payments SDK\n\nAdd the Square SDK to your storefront:\n\n```typescript\nimport { useEffect, useState } from 'react';\n\n// Load Square SDK\nuseEffect(() => {\n  const script = document.createElement('script');\n  script.src = 'https://sandbox.web.squarecdn.com/v1/square.js'; // or production URL\n  script.async = true;\n  document.body.appendChild(script);\n}, []);\n```\n\n### Initialize Payment Form\n\n```typescript\nconst payments = Square.payments(\n  process.env.NEXT_PUBLIC_SQUARE_APPLICATION_ID,\n  process.env.NEXT_PUBLIC_SQUARE_LOCATION_ID\n);\n\nconst card = await payments.card();\nawait card.attach('#card-container');\n\n// Tokenize card when submitting\nconst result = await card.tokenize();\nconst token = result.token;\n```\n\n### Submit Payment\n\n```typescript\nimport { addPaymentToOrder } from '@vendure/core';\n\nconst paymentResult = await addPaymentToOrder({\n  method: 'square-payment',\n  metadata: {\n    sourceId: token, // Square payment token\n  },\n});\n```\n\n---\n\n## 🔄 Payment Flow\n\n### Authorization Flow (Two-Step)\n\nBy default, payments are **authorized** but not captured:\n\n1. Customer submits payment\n2. Square authorizes payment (reserves funds)\n3. Order state: **PaymentAuthorized**\n4. Admin settles payment in Vendure Admin\n5. Square captures funds\n6. Order state: **PaymentSettled**\n\n**Benefits:**\n- Verify inventory before capturing\n- Cancel without refunding\n- Better fraud protection\n\n### Auto-Settlement (One-Step)\n\nTo automatically capture payments, modify the handler:\n\n```typescript\n// In square-payment-handler.ts, line ~92\nautocomplete: true,  // Change from false to true\n```\n\n---\n\n## 🧪 Testing\n\n### Sandbox Mode\n\nUse Square's test card numbers:\n\n| Card Number | Scenario |\n|-------------|----------|\n| `4111 1111 1111 1111` | Successful charge |\n| `4000 0000 0000 0002` | Card declined |\n| `4000 0000 0000 0341` | Insufficient funds |\n\n**Test Card Details:**\n- **CVV:** Any 3 digits (e.g., `111`)\n- **Expiration:** Any future date (e.g., `12/25`)\n- **ZIP Code:** Any 5 digits (e.g., `90210`)\n\nMore test values: https://developer.squareup.com/docs/devtools/sandbox/payments\n\n---\n\n## 🛠️ API Reference\n\n### SquarePlugin.init(options)\n\nInitialize the plugin with Square credentials.\n\n**Parameters:**\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `accessToken` | `string` | Square API access token (required) |\n| `environment` | `'sandbox' \\| 'production'` | Square environment (required) |\n| `locationId` | `string` | Square location ID (required) |\n\n**Example:**\n\n```typescript\nSquarePlugin.init({\n  accessToken: process.env.SQUARE_ACCESS_TOKEN!,\n  environment: 'sandbox',\n  locationId: process.env.SQUARE_LOCATION_ID!,\n})\n```\n\n### squarePaymentHandler\n\nPayment method handler with code `'square-payment'`.\n\n**Methods:**\n\n- **createPayment**: Authorizes payment with Square\n- **settlePayment**: Captures authorized payment\n- **createRefund**: Processes full or partial refunds\n\n---\n\n## 🔐 Security\n\n### PCI Compliance\n\n- ✅ Card data handled entirely by Square\n- ✅ Single-use payment tokens\n- ✅ No sensitive data stored on your server\n- ✅ HTTPS required for production\n\n### Best Practices\n\n- Store access tokens in environment variables\n- Never commit credentials to version control\n- Use sandbox for development/testing\n- Enable HTTPS on production domains\n- Regularly rotate access tokens\n\n---\n\n## 🐛 Troubleshooting\n\n### \"Payment method not found\"\n\n**Solution:** Create payment method in Vendure Admin with handler code `'square-payment'`\n\n### \"Square SDK not loaded\"\n\n**Solution:** Ensure Square Web Payments SDK script is loaded before initializing payment form\n\n### \"Missing Square payment token\"\n\n**Solution:** Card tokenization failed - check card details or Square SDK initialization\n\n### \"Authentication failed\"\n\n**Solution:** Verify Square access token and environment (sandbox vs production)\n\n---\n\n## 📚 Documentation\n\n### Square Developer Resources\n\n- [Square Developer Portal](https://developer.squareup.com/)\n- [Payments API Guide](https://developer.squareup.com/docs/payments-api/overview)\n- [Web Payments SDK](https://developer.squareup.com/docs/web-payments/overview)\n- [Testing Guide](https://developer.squareup.com/docs/devtools/sandbox/payments)\n\n### Vendure Resources\n\n- [Vendure Docs](https://docs.vendure.io/)\n- [Payment Integration Guide](https://docs.vendure.io/guides/core-concepts/payment/)\n- [Plugin Development](https://docs.vendure.io/guides/developer-guide/plugins/)\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/yourusername/vendure-plugin-square.git\ncd vendure-plugin-square\nnpm install\nnpm run build\n```\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n---\n\n## 💪 Credits\n\nBuilt with ❤️ for the Vendure community\n\n**Special Thanks:**\n- Vendure team for the amazing e-commerce framework\n- Square for their robust payment APIs\n- The open-source community\n\n---\n\n## 🚀 Changelog\n\n### v1.0.0 (2025-09-30)\n\n**Initial Release**\n- ✅ Complete Square payment integration\n- ✅ Authorization and settlement support\n- ✅ Refund processing\n- ✅ PCI-compliant tokenization\n- ✅ Sandbox and production environments\n- ✅ Full TypeScript support\n- ✅ Comprehensive error handling\n\n---\n\n**Questions or issues?** Open an issue on [GitHub](https://github.com/yourusername/vendure-plugin-square/issues)\n\n**Want to contribute?** PRs are always welcome! 🎉\n","readmeFilename":"README.md","_rev":"1-604c07b2b1c67f71c586e6f80445e6ce"}