{"_id":"@corepay/qorpay-v3-sdk","_rev":"7-c02464f09c16c191fc00010d350171a5","name":"@corepay/qorpay-v3-sdk","dist-tags":{"latest":"1.6.0"},"versions":{"1.4.0":{"name":"@corepay/qorpay-v3-sdk","version":"1.4.0","keywords":["qorpay","qorcommerce","payment gateway","sdk","typescript","api-client","payments","fintech","ecommerce"],"author":{"name":"QorLabs","email":"developer@qorlabs.io"},"license":"MIT","_id":"@corepay/qorpay-v3-sdk@1.4.0","maintainers":[{"name":"palermo777","email":"palermo777@gmail.com"}],"homepage":"https://github.com/QorLabs/qorpay-v3-sdk#readme","bugs":{"url":"https://github.com/QorLabs/qorpay-v3-sdk/issues"},"dist":{"shasum":"cb5d30f0a68648b9472084f199f215114b0df82b","tarball":"https://registry.npmjs.org/@corepay/qorpay-v3-sdk/-/qorpay-v3-sdk-1.4.0.tgz","fileCount":338,"integrity":"sha512-g/Ic0T5/pcu5lZQYtx+FbAF8kEMW6kn1nJRGYep4mGewk1+sOVeX6WFHFG1Y51BlGBbPTi8k4t10HQfS+jAklg==","signatures":[{"sig":"MEQCIAnrz1dP0hN3TxdY6nuY9vDymCjIzBK707yLi2/r/oKnAiB8GVd88plYGVhQM1ezzGNSNVBn0JRWGs8hPv8jRLIUUg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3522198},"main":"dist/cjs/index.js","types":"dist/types/index.d.ts","module":"dist/esm/index.js","browser":"dist/umd/qorpay-sdk.min.js","engines":{"node":">=14.0.0"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","browser":"./dist/umd/qorpay-sdk.min.js","require":"./dist/cjs/index.js"}},"gitHead":"000fc8d0c5d5db18d84ecabaa0b378254c0458b9","scripts":{"dev":"rollup -c rollup.config.mjs -w","docs":"typedoc --options typedoc.json","lint":"eslint \"src/**/*.ts\" \"tests/**/*.ts\"","size":"node -e \"const fs=require('fs'); const path=require('path'); function getSize(dir) { let size=0; try { const files=fs.readdirSync(dir); files.forEach(file => { const filePath=path.join(dir,file); const stat=fs.statSync(filePath); if(stat.isDirectory()) size+=getSize(filePath); else size+=stat.size; }); } catch(e) {} return size; } const size=getSize('dist'); console.log('Build size:', (size/1024/1024).toFixed(2), 'MB'); try { console.log('Files:'); fs.readdirSync('dist').forEach(f => console.log(' -', f)); } catch(e) { console.log('dist/ not found'); }\"","test":"jest","build":"npm run clean && rollup -c rollup.config.mjs","clean":"rimraf dist docs coverage","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"*.json\" \"*.md\" \"*.js\" \"*.mjs\"","analyze":"node scripts/analyze-coverage.js","prepare":"npm run build","quality":"./scripts/quality-gates.sh","test:ci":"npm run lint && npm test -- --runInBand","coverage":"jest --coverage","lint:fix":"eslint \"src/**/*.ts\" \"tests/**/*.ts\" --fix","progress":"./scripts/update-progress.sh","test:watch":"jest --watch","progress:show":"./scripts/update-progress.sh --show","quality:stats":"./scripts/quality-gates.sh --stats","test:coverage":"jest --coverage","prepublishOnly":"npm run lint && npm run test:coverage && npm run build && npm run docs","coverage:update":"npm run analyze && npm run progress"},"_npmUser":{"name":"palermo777","email":"palermo777@gmail.com"},"repository":{"url":"git+https://github.com/QorLabs/qorpay-v3-sdk.git","type":"git"},"_npmVersion":"10.8.2","description":"Community-driven TypeScript SDK for the QorCommerce V3 API - RESTful wrapper with best practices","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","dependencies":{"zod":"^3.22.4","axios":"^1.6.0","axios-retry":"^4.5.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.57.0","rimraf":"^5.0.5","rollup":"^4.12.1","ts-jest":"^29.1.2","ts-node":"^10.9.2","typedoc":"^0.25.12","prettier":"^3.2.5","typescript":"^5.4.2","@types/jest":"^29.5.12","@types/node":"^20.12.2","eslint-plugin-jest":"^27.9.0","@rollup/plugin-json":"^6.1.0","@rollup/plugin-terser":"^0.4.4","eslint-config-prettier":"^9.1.0","eslint-plugin-prettier":"^5.4.1","@rollup/plugin-commonjs":"^25.0.7","typedoc-plugin-markdown":"^3.17.1","@rollup/plugin-typescript":"^11.1.6","@typescript-eslint/parser":"^7.3.1","@rollup/plugin-node-resolve":"^15.2.3","@typescript-eslint/eslint-plugin":"^7.3.1"},"_npmOperationalInternal":{"tmp":"tmp/qorpay-v3-sdk_1.4.0_1764367928602_0.9793393823861456","host":"s3://npm-registry-packages-npm-production"}},"1.5.0":{"name":"@corepay/qorpay-v3-sdk","version":"1.5.0","keywords":["qorpay","qorcommerce","payment gateway","sdk","typescript","api-client","payments","fintech","ecommerce"],"author":{"name":"QorLabs","email":"developer@qorlabs.io"},"license":"MIT","_id":"@corepay/qorpay-v3-sdk@1.5.0","maintainers":[{"name":"palermo777","email":"palermo777@gmail.com"}],"homepage":"https://github.com/QorLabs/qorpay-v3-sdk#readme","bugs":{"url":"https://github.com/QorLabs/qorpay-v3-sdk/issues"},"dist":{"shasum":"fe9f782b19a0d6c35ea4f420e65f1b339eef30b4","tarball":"https://registry.npmjs.org/@corepay/qorpay-v3-sdk/-/qorpay-v3-sdk-1.5.0.tgz","fileCount":338,"integrity":"sha512-TPXto2mi89t9gcWJWJm/VExvUE7PohYpiXps3uVG/pc2mLtfdZPfgGf6qnckeWjgSYe+uzfpevY74Gv6a+h5tg==","signatures":[{"sig":"MEQCIHy+dGmgKhvCFr2R/eZcx0PMBPQFaDKvVyb2Qg4JubJPAiARGrrKVeS0bCU7sJQUTmFu2OND6L0suU4+6TOHyCiPhA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3522198},"main":"dist/cjs/index.js","types":"dist/types/index.d.ts","module":"dist/esm/index.js","browser":"dist/umd/qorpay-sdk.min.js","engines":{"node":">=14.0.0"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","browser":"./dist/umd/qorpay-sdk.min.js","require":"./dist/cjs/index.js"}},"gitHead":"22d6a4e15dbbb5b37b268ab58893f67dc2d5a7fd","scripts":{"dev":"rollup -c rollup.config.mjs -w","docs":"typedoc --options typedoc.json","lint":"eslint \"src/**/*.ts\" \"tests/**/*.ts\"","size":"node -e \"const fs=require('fs'); const path=require('path'); function getSize(dir) { let size=0; try { const files=fs.readdirSync(dir); files.forEach(file => { const filePath=path.join(dir,file); const stat=fs.statSync(filePath); if(stat.isDirectory()) size+=getSize(filePath); else size+=stat.size; }); } catch(e) {} return size; } const size=getSize('dist'); console.log('Build size:', (size/1024/1024).toFixed(2), 'MB'); try { console.log('Files:'); fs.readdirSync('dist').forEach(f => console.log(' -', f)); } catch(e) { console.log('dist/ not found'); }\"","test":"jest","build":"npm run clean && rollup -c rollup.config.mjs","clean":"rimraf dist docs coverage","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"*.json\" \"*.md\" \"*.js\" \"*.mjs\"","analyze":"node scripts/analyze-coverage.js","prepare":"npm run build","quality":"./scripts/quality-gates.sh","test:ci":"npm run lint && npm test -- --runInBand","coverage":"jest --coverage","lint:fix":"eslint \"src/**/*.ts\" \"tests/**/*.ts\" --fix","progress":"./scripts/update-progress.sh","test:watch":"jest --watch","progress:show":"./scripts/update-progress.sh --show","quality:stats":"./scripts/quality-gates.sh --stats","test:coverage":"jest --coverage","prepublishOnly":"npm run lint && npm run test:coverage && npm run build && npm run docs","coverage:update":"npm run analyze && npm run progress"},"_npmUser":{"name":"palermo777","email":"palermo777@gmail.com"},"repository":{"url":"git+https://github.com/QorLabs/qorpay-v3-sdk.git","type":"git"},"_npmVersion":"10.8.2","description":"Community-driven TypeScript SDK for the QorCommerce V3 API - RESTful wrapper with best practices","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","dependencies":{"zod":"^3.22.4","axios":"^1.6.0","axios-retry":"^4.5.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.57.0","rimraf":"^5.0.5","rollup":"^4.12.1","ts-jest":"^29.1.2","ts-node":"^10.9.2","typedoc":"^0.25.12","prettier":"^3.2.5","typescript":"^5.4.2","@types/jest":"^29.5.12","@types/node":"^20.12.2","eslint-plugin-jest":"^27.9.0","@rollup/plugin-json":"^6.1.0","@rollup/plugin-terser":"^0.4.4","eslint-config-prettier":"^9.1.0","eslint-plugin-prettier":"^5.4.1","@rollup/plugin-commonjs":"^25.0.7","typedoc-plugin-markdown":"^3.17.1","@rollup/plugin-typescript":"^11.1.6","@typescript-eslint/parser":"^7.3.1","@rollup/plugin-node-resolve":"^15.2.3","@typescript-eslint/eslint-plugin":"^7.3.1"},"_npmOperationalInternal":{"tmp":"tmp/qorpay-v3-sdk_1.5.0_1764624689227_0.11649140219441789","host":"s3://npm-registry-packages-npm-production"}},"1.6.0":{"name":"@corepay/qorpay-v3-sdk","version":"1.6.0","description":"Community-driven TypeScript SDK for the QorCommerce V3 API - RESTful wrapper with best practices","author":{"name":"QorLabs","email":"developer@qorlabs.io"},"license":"MIT","publishConfig":{"access":"public"},"keywords":["qorpay","qorcommerce","payment gateway","sdk","typescript","api-client","payments","fintech","ecommerce"],"repository":{"type":"git","url":"git+https://github.com/QorLabs/qorpay-v3-sdk.git"},"bugs":{"url":"https://github.com/QorLabs/qorpay-v3-sdk/issues"},"homepage":"https://github.com/QorLabs/qorpay-v3-sdk#readme","engines":{"node":">=14.0.0"},"main":"dist/cjs/index.js","module":"dist/esm/index.js","browser":"dist/umd/qorpay-sdk.min.js","types":"dist/types/index.d.ts","exports":{".":{"import":"./dist/esm/index.js","require":"./dist/cjs/index.js","browser":"./dist/umd/qorpay-sdk.min.js","types":"./dist/types/index.d.ts"}},"sideEffects":false,"scripts":{"dev":"rollup -c rollup.config.mjs -w","build":"npm run clean && rollup -c rollup.config.mjs","test":"jest","test:ci":"npm run lint && npm test -- --runInBand","test:coverage":"jest --coverage","coverage":"jest --coverage","test:watch":"jest --watch","lint":"eslint \"src/**/*.ts\" \"tests/**/*.ts\"","lint:fix":"eslint \"src/**/*.ts\" \"tests/**/*.ts\" --fix","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"*.json\" \"*.md\" \"*.js\" \"*.mjs\"","docs":"typedoc --options typedoc.json","quality":"./scripts/quality-gates.sh","quality:stats":"./scripts/quality-gates.sh --stats","progress":"./scripts/update-progress.sh","progress:show":"./scripts/update-progress.sh --show","analyze":"node scripts/analyze-coverage.js","coverage:update":"npm run analyze && npm run progress","size":"node -e \"const fs=require('fs'); const path=require('path'); function getSize(dir) { let size=0; try { const files=fs.readdirSync(dir); files.forEach(file => { const filePath=path.join(dir,file); const stat=fs.statSync(filePath); if(stat.isDirectory()) size+=getSize(filePath); else size+=stat.size; }); } catch(e) {} return size; } const size=getSize('dist'); console.log('Build size:', (size/1024/1024).toFixed(2), 'MB'); try { console.log('Files:'); fs.readdirSync('dist').forEach(f => console.log(' -', f)); } catch(e) { console.log('dist/ not found'); }\"","clean":"rimraf dist docs coverage","prepublishOnly":"npm run lint && npm run test:coverage && npm run build && npm run docs","prepare":"npm run build"},"dependencies":{"axios":"^1.6.0","axios-retry":"^4.5.0","zod":"^3.22.4"},"devDependencies":{"@rollup/plugin-commonjs":"^25.0.7","@rollup/plugin-json":"^6.1.0","@rollup/plugin-node-resolve":"^15.2.3","@rollup/plugin-terser":"^0.4.4","@rollup/plugin-typescript":"^11.1.6","@types/jest":"^29.5.12","@types/node":"^20.12.2","@typescript-eslint/eslint-plugin":"^7.3.1","@typescript-eslint/parser":"^7.3.1","eslint":"^8.57.0","eslint-config-prettier":"^9.1.0","eslint-plugin-jest":"^27.9.0","eslint-plugin-prettier":"^5.4.1","jest":"^29.7.0","prettier":"^3.2.5","rimraf":"^5.0.5","rollup":"^4.12.1","ts-jest":"^29.1.2","ts-node":"^10.9.2","typedoc":"^0.25.12","typedoc-plugin-markdown":"^3.17.1","typescript":"^5.4.2"},"_id":"@corepay/qorpay-v3-sdk@1.6.0","gitHead":"81c6564664908f4708822cac4f8de0f30bf0e5a3","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-FBVayUImumgWzb1b3RtzNdNE0x6aHGJERqHCjaHSgoZCM/KTI9dix/jA9hKw+sDml0UR0mc62bloamkqxdMI1g==","shasum":"aec2d826970364ec8ed7bad3ffd0557757df5178","tarball":"https://registry.npmjs.org/@corepay/qorpay-v3-sdk/-/qorpay-v3-sdk-1.6.0.tgz","fileCount":338,"unpackedSize":3519401,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFbUPoiEsuQT4kQgfHXwaR64mo1Slz/weCZBwY26wx3GAiBMUGeDTs9qv9Ye6oejYJ8AwwGYhEYyR3RIYe49K6FrIQ=="}]},"_npmUser":{"name":"palermo777","email":"palermo777@gmail.com"},"directories":{},"maintainers":[{"name":"palermo777","email":"palermo777@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/qorpay-v3-sdk_1.6.0_1764646309155_0.5385536691236077"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-28T22:12:08.517Z","modified":"2025-12-02T03:31:49.671Z","1.0.0":"2025-06-13T23:12:29.444Z","1.4.0":"2025-11-28T22:12:08.887Z","1.5.0":"2025-12-01T21:31:29.471Z","1.6.0":"2025-12-02T03:31:49.434Z"},"bugs":{"url":"https://github.com/QorLabs/qorpay-v3-sdk/issues"},"author":{"name":"QorLabs","email":"developer@qorlabs.io"},"license":"MIT","homepage":"https://github.com/QorLabs/qorpay-v3-sdk#readme","keywords":["qorpay","qorcommerce","payment gateway","sdk","typescript","api-client","payments","fintech","ecommerce"],"repository":{"type":"git","url":"git+https://github.com/QorLabs/qorpay-v3-sdk.git"},"description":"Community-driven TypeScript SDK for the QorCommerce V3 API - RESTful wrapper with best practices","maintainers":[{"name":"palermo777","email":"palermo777@gmail.com"}],"readme":"# QorPay V3 API SDK\n\n**⚠️ DISCLAIMER**: This is a community-driven SDK, NOT an official QorPay Inc. product. All financial and security responsibilities remain with the user. See [⚠️ IMPORTANT DISCLAIMER](#-important-disclaimer) for complete details.\n\n---\n\nA TypeScript SDK for QorPay payment processing API with type-safe interfaces and REST-compliant methods.\n\n## WHAT IT DOES\n\nProcess payments, manage customers, handle subscriptions, and more through QorPay's payment platform.\n\n**Main Features:**\n\n- Accept credit/debit card payments\n- Process ACH bank transfers\n- Manage customer payment methods\n- Handle subscription billing\n- Process marketplaces with split payments\n- Manage disputes and chargebacks\n- Validate payment data\n- Process webhooks\n- Generate reports\n\n## HOW TO USE IT\n\n### Installation Overview\n\nThis SDK is published to **GitHub Packages Registry**, which requires authentication. See the [Installation](#-installation) section below for detailed instructions and multiple installation options.\n\n### Basic Setup\n\n```typescript\nimport { QorPayClient } from '@corepay/qorpay-v3-sdk';\n\nconst qorpay = new QorPayClient({\n  appKey: 'your-app-key',\n  clientKey: 'your-client-key',\n  environment: 'sandbox', // or 'production'\n});\n```\n\n### Common Tasks\n\n**Process a Card Payment**\n\n```typescript\nconst payment = await qorpay.payments.create({\n  amount: 100.5,\n  currency: 'USD',\n  card: {\n    number: '4111111111111111',\n    expiryMonth: '12',\n    expiryYear: '25',\n    cvv: '123',\n  },\n  customer: {\n    email: 'customer@example.com',\n    name: 'John Doe',\n  },\n});\n```\n\n**Create a Customer**\n\n```typescript\nconst customer = await qorpay.customers.create({\n  email: 'customer@example.com',\n  name: 'John Doe',\n  phone: '+1-555-123-4567',\n});\n```\n\n**Process a Refund**\n\n```typescript\nconst refund = await qorpay.payments.refund('pay_1234567890', {\n  amount: 50.0,\n  reason: 'Customer requested refund',\n});\n```\n\n**List Transactions**\n\n```typescript\nconst transactions = await qorpay.transactions.list({\n  status: 'approved',\n  limit: 25,\n  startDate: new Date('2024-01-01'),\n});\n```\n\n**Validate a Card**\n\n```typescript\nconst validation = await qorpay.utilities.validateCard({\n  cardNumber: '4111111111111111',\n  expiryMonth: '12',\n  expiryYear: '25',\n  cvv: '123',\n});\n```\n\n## 📚 Examples & Code Patterns\n\n### 🟢 Quick Start Examples\n\n```bash\n# Explore comprehensive examples\nls examples/\nexamples/\n├── README.md                    # Complete examples guide\n├── basic/sdk-setup.ts           # SDK initialization & basic payments\n├── basic/ach-payments.ts        # Bank transfer payments\n├── security/secure-token-payments.ts # Secure token payments\n├── advanced/error-handling.ts   # Production-ready error handling\n├── advanced/webhook-integration.ts # Real-time webhook processing\n├── advanced/recurring-payments.ts # Subscription billing\n└── testing/testing-with-sdk.ts  # Testing patterns & utilities\n```\n\n### 🔒 Security & Best Practices\n\n### Token Payment Security\n\n**🚨 IMPORTANT: Customer ID Required for Token Payments**\n\nFor security and compliance, all token payments **must** include a `customer_id`. This prevents token hijacking and ensures proper audit trails.\n\n```typescript\n// ✅ SECURE: Token payment with customer verification\nconst customer = await qorpay.customers.create({\n  email: 'john@example.com',\n  firstName: 'John',\n  lastName: 'Doe',\n});\n\n// Create a token linked to the customer\nconst token = await qorpay.paymentTokens.createCardToken({\n  card_number: '4111111111111111',\n  card_exp: '1225',\n  customer_id: customer.id, // Link token to customer\n  card_holder: 'John Doe',\n});\n\n// Process payment with token (customer_id required)\nconst payment = await qorpay.payments.saleToken({\n  mid: 'your-mid',\n  amount: '29.99',\n  creditcard: token.token,\n  customer_id: customer.id, // REQUIRED: Must match token owner\n  customer_validation: {\n    name_match: true,\n    email_match: true,\n  },\n});\n\n// ❌ BLOCKED: Token payment without customer_id\nawait qorpay.payments.saleToken({\n  creditcard: 'tok_abc123',\n  amount: '29.99',\n  // customer_id: 'MISSING' -> ValidationError!\n});\n```\n\n### One-Time vs Token Payments\n\n```typescript\n// ✅ One-time payments don't need customer_id\nawait qorpay.payments.saleManual({\n  mid: 'your-mid',\n  amount: '29.99',\n  creditcard: '4111111111111111', // Raw card, not token\n  cvv: '123',\n  month: '12',\n  year: '25',\n  // No customer_id needed for one-time payments\n});\n\n// ⚠️ Token payments ALWAYS require customer_id\nawait qorpay.payments.saleToken({\n  creditcard: 'tok_abc123', // Stored token\n  amount: '29.99',\n  customer_id: 'cust_xyz789', // REQUIRED for security\n});\n```\n\n### Customer Validation Options\n\nEnhance security with optional customer validation:\n\n```typescript\nawait qorpay.payments.saleToken({\n  creditcard: 'tok_abc123',\n  amount: '29.99',\n  customer_id: 'cust_xyz789',\n  customer_validation: {\n    name_match: true, // Customer name matches token holder\n    email_match: true, // Customer email matches token holder\n    ip_match: true, // Customer IP matches previous usage\n  },\n});\n```\n\n### Security Benefits\n\n- **🛡️ Fraud Prevention**: Tokens can only be used by their owning customer\n- **📋 Audit Trails**: Clear customer-token relationships for compliance\n- **🔒 Regulatory Compliance**: Meets PCI-DSS requirements for stored payment methods\n- **💼 Business Logic**: Prevents orphaned tokens and misuse\n\n## 📦 Installation\n\n**⚠️ IMPORTANT: This package is published to GitHub Packages Registry (private registry), not the public npm registry. Authentication is required.**\n\n### Prerequisites\n\nBefore installing, you need:\n- A GitHub account\n- A Personal Access Token with `read:packages` scope\n\n**Create GitHub Personal Access Token:**\n1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)\n2. Click \"Generate new token\"\n3. Add the `read:packages` scope\n4. Copy the token (it won't be shown again)\n\n### Option 1: Project-Level Configuration (Recommended)\n\n**Step 1:** Create or add to your project's `.npmrc` file:\n\n```\n@corepay:registry=https://npm.pkg.github.com/\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n```\n\n**Step 2:** Set the environment variable with your GitHub token:\n\n```bash\n# In your terminal or CI/CD\nexport GITHUB_TOKEN=your_github_personal_access_token\n```\n\n**Step 3:** Install normally:\n\n```bash\nnpm install @corepay/qorpay-v3-sdk\n```\n\n### Option 2: Global Configuration\n\nAdd to your global `~/.npmrc`:\n\n```\n@corepay:registry=https://npm.pkg.github.com/\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n```\n\nThen set the environment variable:\n\n```bash\nexport GITHUB_TOKEN=your_github_personal_access_token\nnpm install @corepay/qorpay-v3-sdk\n```\n\n### Option 3: Install Directly from GitHub (No Auth Required)\n\n**Advanced users only - requires manual build setup**\n\n```bash\n# Clone the repository\ngit clone https://github.com/QorLabs/qorpay-v3-sdk.git\ncd qorpay-v3-sdk\n\n# Install dependencies\nnpm install\n\n# Build the package (creates dist/ folder)\nnpm run build\n\n# Install locally from the built package\nnpm install ./dist\n```\n\n**Or use specific version:**\n```bash\n# Clone specific tag\ngit clone --branch v1.4.0 https://github.com/QorLabs/qorpay-v3-sdk.git\ncd qorpay-v3-sdk\n\n# Build and install\nnpm install && npm run build\nnpm install ./dist\n```\n\n**Note:** This method is more complex as you need to build the package yourself. Options 1-2 are recommended for most users.\n\n### Option 4: Manual Installation\n\n```bash\ngit clone https://github.com/QorLabs/qorpay-v3-sdk.git\ncd qorpay-v3-sdk\nnpm install\nnpm run build\n# Then use the dist/ files or link locally\n```\n\n### Troubleshooting Installation\n\n**Error: \"authentication token not provided\"**\n- Ensure you've set the `GITHUB_TOKEN` environment variable\n- Verify your token has `read:packages` scope\n- Check that your `.npmrc` file is configured correctly\n\n**Error: \"404 Not Found\"**\n- Verify the package scope is `@corepay`\n- Ensure you're using the GitHub registry URL\n- Check that your token is valid and not expired\n\n**CI/CD Setup:**\n```yaml\n# GitHub Actions example\n- name: Install dependencies\n  env:\n    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n  run: npm install @corepay/qorpay-v3-sdk\n```\n\n## 🚀 Quick Start\n\n```typescript\nimport { QorPayClient } from '@corepay/qorpay-v3-sdk';\n\nconst qorpay = new QorPayClient({\n  appKey: 'your-app-key',\n  clientKey: 'your-client-key',\n  environment: 'sandbox',\n});\n\n// Create a payment - clean and simple!\nconst payment = await qorpay.payments.create({\n  amount: 100.5, // Number, not string\n  card: {\n    number: '4111111111111111',\n    expiryMonth: '12',\n    expiryYear: '25',\n    cvv: '123',\n  },\n  customer: {\n    email: 'customer@example.com',\n    name: 'John Doe',\n  },\n});\n\nconsole.log(payment.id); // txn_abc123\nconsole.log(payment.status); // 'approved'\nconsole.log(payment.amount); // 100.5 (number)\n```\n\n## WHERE TO FIND THINGS\n\n### API Resources\n\nAll available through `qorpay.resourceName.method()`:\n\n| Resource           | What It Does                                      | Example Usage                           |\n| ------------------ | ------------------------------------------------- | --------------------------------------- |\n| **Payments**       | Process card/ACH/cash payments, refunds, captures | `qorpay.payments.create({...})`         |\n| **Transactions**   | View payment history and transaction details      | `qorpay.transactions.list({...})`       |\n| **Customers**      | Manage customer data and payment methods          | `qorpay.customers.create({...})`        |\n| **Payment Tokens** | Store payment methods securely                    | `qorpay.paymentTokens.create({...})`    |\n| **ACH Payments**   | Process bank transfers                            | `qorpay.achPayments.createDebit({...})` |\n| **Subscriptions**  | Manage recurring billing                          | `qorpay.subscriptions.create({...})`    |\n| **Gift Cards**     | Issue and redeem gift cards                       | `qorpay.giftCards.create({...})`        |\n| **Disputes**       | Handle chargebacks                                | `qorpay.disputes.create({...})`         |\n| **Webhooks**       | Configure event notifications                     | `qorpay.webhooks.create({...})`         |\n| **Utilities**      | Validate cards, BIN lookup, etc.                  | `qorpay.utilities.validateCard({...})`  |\n\n### Documentation & Resources\n\n- **API Documentation**: [QorPay API Docs](https://docs.qorcommerce.io/)\n- **Type Definitions**: Inline JSDoc in your IDE\n- **Code Examples**: `examples/` directory - Comprehensive usage patterns\n- **Test Examples**: `tests/` directory - Testing patterns and utilities\n\n### Error Handling\n\n```typescript\ntry {\n  const payment = await qorpay.payments.create(paymentData);\n} catch (error) {\n  if (error.code === 'card_declined') {\n    // Handle declined card\n  } else if (error.code === 'insufficient_funds') {\n    // Handle insufficient funds\n  }\n}\n```\n\n## ALL RESOURCES & METHODS\n\n### Payments\n\n```typescript\nqorpay.payments.create(data); // Process payment\nqorpay.payments.capture(id); // Capture authorized payment\nqorpay.payments.void(id); // Void payment\nqorpay.payments.refund(id, data); // Refund payment\nqorpay.payments.get(id); // Get payment details\nqorpay.payments.list(filters); // List payments\n```\n\n### Customers\n\n```typescript\nqorpay.customers.create(data); // Create customer\nqorpay.customers.get(id); // Get customer\nqorpay.customers.update(id, data); // Update customer\nqorpay.customers.delete(id); // Delete customer\nqorpay.customers.list(filters); // List customers\n```\n\n### All Other Resources\n\nEach resource follows the same pattern: `create()`, `get()`, `list()`, `update()`, `delete()` where applicable.\n\n### Core Resources\n\n| Resource           | Methods                                                           | Examples                                         |\n| ------------------ | ----------------------------------------------------------------- | ------------------------------------------------ |\n| **Payments**       | `create()`, `authorize()`, `capture()`, `void()`, `refund()`      | `qorpay.payments.create({...})`                  |\n| **Transactions**   | `get()`, `list()`, `listByCustomer()`, `listByBatch()`            | `qorpay.transactions.list({status: 'approved'})` |\n| **Payment Tokens** | `createCardToken()`, `getCardToken()`, `listExpiringCardTokens()` | `qorpay.paymentTokens.createCardToken({...})`    |\n| **Customers**      | `create()`, `get()`, `list()`, `update()`, `delete()`             | `qorpay.customers.create({email: '...'})`        |\n| **ACH Payments**   | `createDebit()`, `createCredit()`, `void()`, `refund()`           | `qorpay.achPayments.createDebit({...})`          |\n| **Utilities**      | `validateCard()`, `lookupBin()`, `validateRouting()`              | `qorpay.utilities.validateCard('411111...')`     |\n\n## DEVELOPMENT\n\n### Setup\n\n```bash\nnpm install\nnpm test        # Run tests\nnpm run build   # Build the package\n```\n\n### Testing\n\n```bash\nnpm run test:coverage  # See coverage report\nnpm run test:watch     # Watch mode\n```\n\n### Status\n\n- **API Coverage**: 137 endpoints across 8 resource classes\n- **Test Coverage**: 95.42% statements, 95.52% branches, 90.53% functions\n- **Test Suite**: 900 passing tests (100% success rate)\n- **Type Safety**: 100% (zero `any` types, 0 TS errors/warnings)\n- **Code Quality**: 0 ESLint errors/warnings\n- **Bundle Size**: 2.82 MB total (ESM, CJS, UMD)\n\n## 🏗️ Project Structure\n\n```\nqorpay-v3-sdk/\n├── src/\n│   ├── client/          # HTTP client and main SDK client\n│   ├── resources/       # Resource classes (Payments, Customers, etc.)\n│   ├── types/           # TypeScript type definitions\n│   ├── schemas/         # Zod validation schemas\n│   ├── errors/          # Custom error classes\n│   └── index.ts         # Main export\n├── tests/\n│   ├── unit/            # Unit tests\n│   └── integration/     # Integration tests with MSW\n├── examples/            # Comprehensive usage examples\n│   ├── basic/           # Basic SDK usage patterns\n│   ├── advanced/        # Advanced implementations\n│   ├── security/        # Security best practices\n│   └── testing/         # Testing patterns and utilities\n└── scripts/             # Utility scripts\n```\n\n## 🧪 Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Type check\nnpm run type-check\n\n# Lint\nnpm run lint\n\n# Build\nnpm run build\n\n# Run all quality gates\nnpm run type-check && npm test && npm run lint && npm run build\n```\n\n## 📊 Current Status\n\n- **API Coverage**: 137 endpoints across 8 resource classes (100% complete)\n- **Test Coverage**: 95.42% statements, 95.52% branches, 90.53% functions\n- **Test Suite**: 900 passing tests (100% success rate)\n- **Type Safety**: 100% (zero `any` types, 0 TS errors/warnings)\n- **Code Quality**: 0 ESLint errors/warnings\n- **Input Validation**: Zod schemas for all API inputs\n- **Bundle Size**: 2.82 MB total (ESM, CJS, UMD)\n\n## Implementation Status\n\n### Available Resources\n\nAll 8 resources are fully implemented with REST-compliant APIs:\n\n- **Payments** (22 endpoints) - Card, ACH, cash, and gift card payments with full lifecycle\n- **Transactions** (16 endpoints) - Transaction management and reporting with POD\n- **Payment Tokens** (11 endpoints) - Card and ACH tokenization with security\n- **Customers** (6 endpoints) - Customer CRUD operations\n- **ACH Payments** (6 endpoints) - ACH-specific payment operations\n- **Utilities** (16 endpoints) - Validation and utility functions\n- **Webhooks** (9 endpoints) - Webhook configuration and management\n- **Payment Methods** (6 endpoints) - Payment method management\n- **Gift Cards** (6 endpoints) - Gift card operations\n- **Deposits** (4 endpoints) - Deposit and payout management\n- **Disputes** (4 endpoints) - Dispute handling and management\n- **Payment Forms** (8 endpoints) - Payment form management\n- **Proof of Delivery** (6 endpoints) - Delivery verification\n- **Cash Payments** (4 endpoints) - Cash payment processing\n- **Channels** (12 endpoints) - Channel and marketplace operations\n- **Plans** (7 endpoints) - Subscription plan management\n\n## 🤝 Contributing\n\n1. Check the `examples/` directory for usage patterns and best practices\n2. Follow existing code patterns and architecture\n3. Ensure all tests pass (`npm test`)\n4. Maintain 100% type safety (no `any` types)\n5. Add tests for new features\n6. Update documentation and examples as needed\n\n## 📝 License\n\nMIT\n\n---\n\n## ⚠️ IMPORTANT DISCLAIMER\n\n**This SDK is NOT provided by, endorsed by, or affiliated with QorPay Inc. (https://qorpay.com)**\n\nThis SDK is an independent, community-driven implementation created as a best-practice RESTful wrapper around the QorCommerce V3 APIs (https://docs.qorcommerce.io).\n\n### 🚨 USE AT YOUR OWN RISK\n\n**NO WARRANTY**: This software is provided \"AS IS\" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement.\n\n**NO LIABILITY**: In no event shall the authors, contributors, or maintainers of this SDK be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.\n\n**FINANCIAL RISK**: Payment processing involves financial transactions and sensitive data. Users are solely responsible for:\n- Testing thoroughly before production use\n- Ensuring compliance with PCI DSS and other financial regulations\n- Validating all transactions and business logic\n- Implementing appropriate security measures\n- Monitoring for fraudulent activity\n\n**NO OFFICIAL SUPPORT**: This SDK does not come with official support from QorPay Inc. For official QorPay support, contact QorPay directly through their official channels.\n\n### ✅ WHAT THIS SDK PROVIDES\n\n- **Community Best Practices**: RESTful design patterns and modern TypeScript implementation\n- **Developer Experience**: Type-safe interfaces and comprehensive documentation\n- **Educational Value**: Reference implementation for API integration patterns\n- **Open Source Collaboration**: Community-driven improvements and contributions\n\n### 📋 RECOMMENDATIONS\n\n1. **TEST THOROUGHLY**: Always test in sandbox environment before production\n2. **REVIEW CODE**: Understand the implementation before using in production\n3. **MONITOR TRANSACTIONS**: Implement proper logging and monitoring\n4. **SECURITY AUDIT**: Conduct security reviews before production deployment\n5. **OFFICIAL DOCUMENTATION**: Always reference the official QorCommerce API documentation\n\n### 🔗 OFFICIAL RESOURCES\n\n- **QorPay Inc.**: https://qorpay.com\n- **Official API Documentation**: https://docs.qorcommerce.io\n- **Official Support**: Contact QorPay Inc. directly for official support\n\n## 🔗 Links\n\n- [QorPay API Documentation](https://docs.qorcommerce.io/)\n- [GitHub Repository](https://github.com/corepay/qorpay-v3-sdk)\n\n---\n","readmeFilename":"README.md"}