{"_id":"@carllee1983/tappay-backend-payment-node","_rev":"6-6d7b49793b54de6866725892750bb2c1","name":"@carllee1983/tappay-backend-payment-node","dist-tags":{"latest":"1.8.0"},"versions":{"1.3.0":{"name":"@carllee1983/tappay-backend-payment-node","version":"1.3.0","keywords":["tappay","payment","payment-gateway","credit-card","debit-card","3d-secure","apple-pay","google-pay","line-pay","jkopay","taiwan","fintech","e-commerce","sdk","typescript","nodejs"],"author":{"name":"Carl Lee","email":"carllee1983@gmail.com"},"license":"MIT","_id":"@carllee1983/tappay-backend-payment-node@1.3.0","maintainers":[{"name":"carllee1983","email":"yashino538@gmail.com"}],"homepage":"https://github.com/CarlLee1983/tappay-backend-payment-node#readme","bugs":{"url":"https://github.com/CarlLee1983/tappay-backend-payment-node/issues"},"dist":{"shasum":"ac863cc800dec3cef5b21f9481da81a0960831f9","tarball":"https://registry.npmjs.org/@carllee1983/tappay-backend-payment-node/-/tappay-backend-payment-node-1.3.0.tgz","fileCount":38,"integrity":"sha512-AjR/mkWs/zf1CP7ZZWLuTkWQSZynArRf/3pGiiCxLx/yzNU+FHXrLL6zOD7a1kKhQINvbfJZs1iMI5RH94gKXA==","signatures":[{"sig":"MEQCIBn7e4r3cdtlEZVXXjxwwYhP9U2o34qPWHDV98dvfZW+AiBcv9uABlL6cE0/jqC6zOdCENqrH6lSurMYK0aO9tYUzQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":174849},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"04a3cc61e33991f18c1ae15bc111f137e949ed3a","scripts":{"lint":"biome lint ./src ./tests","test":"bun test","build":"bun run build.ts","check":"biome check ./src ./tests","format":"biome format --write ./src ./tests","prepare":"simple-git-hooks","test:ci":"bun test --coverage --coverage-threshold=100","lint:fix":"biome lint --write ./src ./tests","check:fix":"biome check --write ./src ./tests","typecheck":"tsc --noEmit","format:check":"biome format ./src ./tests","test:coverage":"bun test --coverage","prepublishOnly":"bun run typecheck && bun run check && bun run test:ci && bun run build"},"_npmUser":{"name":"carllee1983","email":"yashino538@gmail.com"},"repository":{"url":"git+https://github.com/CarlLee1983/tappay-backend-payment-node.git","type":"git"},"_npmVersion":"10.8.2","description":"TapPay Backend Payment SDK for Node.js - A TypeScript SDK for TapPay Backend Payment APIs with full type support","directories":{},"lint-staged":{"*.test.{ts,tsx}":["bun test --bail"],"*.{js,ts,cjs,mjs}":["biome check --write","bash -c 'bun run typecheck'"]},"_nodeVersion":"20.18.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.9.3","lint-staged":"^16.2.7","@biomejs/biome":"^2.3.8","simple-git-hooks":"^2.13.1"},"simple-git-hooks":{"pre-commit":"export PATH=\"$HOME/.bun/bin:$PATH\" && bun run test && bunx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/tappay-backend-payment-node_1.3.0_1765560256311_0.15864883333907542","host":"s3://npm-registry-packages-npm-production"}},"1.3.1":{"name":"@carllee1983/tappay-backend-payment-node","version":"1.3.1","keywords":["tappay","payment","payment-gateway","credit-card","debit-card","3d-secure","apple-pay","google-pay","line-pay","jkopay","taiwan","fintech","e-commerce","sdk","typescript","nodejs"],"author":{"name":"Carl Lee","email":"carllee1983@gmail.com"},"license":"MIT","_id":"@carllee1983/tappay-backend-payment-node@1.3.1","maintainers":[{"name":"carllee1983","email":"yashino538@gmail.com"}],"homepage":"https://github.com/CarlLee1983/tappay-backend-payment-node#readme","bugs":{"url":"https://github.com/CarlLee1983/tappay-backend-payment-node/issues"},"dist":{"shasum":"570b533b30b363a3d8bfb63eecab58965f4c74b8","tarball":"https://registry.npmjs.org/@carllee1983/tappay-backend-payment-node/-/tappay-backend-payment-node-1.3.1.tgz","fileCount":38,"integrity":"sha512-/4SGdH29kcbcKITD8eZXIYpT6V2hfyVrVmj759Zelu0G5z4Qz2N6r9ab6rJgJlmsY9aXdnahFrJZsZYi5+LycQ==","signatures":[{"sig":"MEQCIDe6xqVxy2WPoG3BFNpnbM5YVr6iNjM367EF7XKOFTqtAiA3BPX8P7PEoQRfqGAiGmWJgd3+wcEBTwPL9HEYUT/8sg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":174849},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"f288fba1a6b583dbdfa8326b43babb5277ca3713","scripts":{"lint":"biome lint ./src ./tests","test":"bun test","build":"bun run build.ts","check":"biome check ./src ./tests","format":"biome format --write ./src ./tests","prepare":"simple-git-hooks","test:ci":"bun test --coverage --coverage-threshold=100","lint:fix":"biome lint --write ./src ./tests","check:fix":"biome check --write ./src ./tests","typecheck":"tsc --noEmit","format:check":"biome format ./src ./tests","test:coverage":"bun test --coverage","prepublishOnly":"bun run typecheck && bun run check && bun run test:ci && bun run build"},"_npmUser":{"name":"carllee1983","email":"yashino538@gmail.com"},"repository":{"url":"git+https://github.com/CarlLee1983/tappay-backend-payment-node.git","type":"git"},"_npmVersion":"10.8.2","description":"TapPay Backend Payment SDK for Node.js - A TypeScript SDK for TapPay Backend Payment APIs with full type support","directories":{},"lint-staged":{"*.test.{ts,tsx}":["bun test --bail"],"*.{js,ts,cjs,mjs}":["biome check --write","bash -c 'bun run typecheck'"]},"_nodeVersion":"20.18.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.9.3","lint-staged":"^16.2.7","@biomejs/biome":"^2.3.8","simple-git-hooks":"^2.13.1"},"simple-git-hooks":{"pre-commit":"export PATH=\"$HOME/.bun/bin:$PATH\" && bun run test && bunx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/tappay-backend-payment-node_1.3.1_1765560771747_0.6484899019963317","host":"s3://npm-registry-packages-npm-production"}},"1.6.0":{"name":"@carllee1983/tappay-backend-payment-node","version":"1.6.0","keywords":["tappay","payment","payment-gateway","credit-card","debit-card","3d-secure","apple-pay","google-pay","line-pay","jkopay","taiwan","fintech","e-commerce","sdk","typescript","nodejs"],"author":{"name":"Carl Lee","email":"carllee1983@gmail.com"},"license":"MIT","_id":"@carllee1983/tappay-backend-payment-node@1.6.0","maintainers":[{"name":"carllee1983","email":"yashino538@gmail.com"}],"homepage":"https://github.com/CarlLee1983/tappay-backend-payment-node#readme","bugs":{"url":"https://github.com/CarlLee1983/tappay-backend-payment-node/issues"},"dist":{"shasum":"5edfa9cc0af77f1b1bad1986a2bc8bb4f770460b","tarball":"https://registry.npmjs.org/@carllee1983/tappay-backend-payment-node/-/tappay-backend-payment-node-1.6.0.tgz","fileCount":38,"integrity":"sha512-T6AScdxFnLMA8gVHc9XlX8Qn94268ik1MfAXHmPmAWmM5yNPOtgu9rL5ahcuzRZgPy1dOP7JJpxBKKaGl3FIBA==","signatures":[{"sig":"MEYCIQCPgE384xfGDPIDGFKSgk0VspBEoIhrJlw9R1sHFDmqTgIhAJ3siRRePwflR116y241xKlRo3Hsz4+uqLQ4yiNvZ2Xn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":174849},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"0e481182b75fd00628714d775725b367f9c4ebe7","scripts":{"lint":"biome lint ./src ./tests","test":"bun test","build":"bun run build.ts","check":"biome check ./src ./tests","format":"biome format --write ./src ./tests","prepare":"simple-git-hooks","test:ci":"bun test --coverage --coverage-threshold=100","lint:fix":"biome lint --write ./src ./tests","check:fix":"biome check --write ./src ./tests","typecheck":"tsc --noEmit","format:check":"biome format ./src ./tests","test:coverage":"bun test --coverage","prepublishOnly":"bun run typecheck && bun run check && bun run test:ci && bun run build"},"_npmUser":{"name":"carllee1983","email":"yashino538@gmail.com"},"repository":{"url":"git+https://github.com/CarlLee1983/tappay-backend-payment-node.git","type":"git"},"_npmVersion":"10.8.2","description":"TapPay Backend Payment SDK for Node.js - A TypeScript SDK for TapPay Backend Payment APIs with full type support","directories":{},"lint-staged":{"*.test.{ts,tsx}":["bun test --bail"],"*.{js,ts,cjs,mjs}":["biome check --write","bash -c 'bun run typecheck'"]},"_nodeVersion":"20.19.6","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.9.3","lint-staged":"^16.2.7","@biomejs/biome":"^2.3.8","simple-git-hooks":"^2.13.1"},"simple-git-hooks":{"pre-commit":"export PATH=\"$HOME/.bun/bin:$PATH\" && bun run test && bunx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/tappay-backend-payment-node_1.6.0_1765599541266_0.5938478211129079","host":"s3://npm-registry-packages-npm-production"}},"1.7.0":{"name":"@carllee1983/tappay-backend-payment-node","version":"1.7.0","keywords":["tappay","payment","payment-gateway","credit-card","debit-card","3d-secure","apple-pay","google-pay","line-pay","jkopay","taiwan","fintech","e-commerce","sdk","typescript","nodejs"],"author":{"name":"Carl Lee","email":"carllee1983@gmail.com"},"license":"MIT","_id":"@carllee1983/tappay-backend-payment-node@1.7.0","maintainers":[{"name":"carllee1983","email":"yashino538@gmail.com"}],"homepage":"https://github.com/CarlLee1983/tappay-backend-payment-node#readme","bugs":{"url":"https://github.com/CarlLee1983/tappay-backend-payment-node/issues"},"dist":{"shasum":"20e38244c5ba5c0a995ff7be7abf8e0ea6ed925b","tarball":"https://registry.npmjs.org/@carllee1983/tappay-backend-payment-node/-/tappay-backend-payment-node-1.7.0.tgz","fileCount":38,"integrity":"sha512-+AFct9z/8Xc985hG5xSCOP10KolEDQoXLrbzVyBBOaYDgeLnR3LK8NXpMR/3ajAIQzx2uyDMYSy9Jj7t5O2wxw==","signatures":[{"sig":"MEUCIF7jsSYazo/fQKtTBWfo4lR3VuWc3j5LDrLT0ZWGZG0UAiEAygLnAtpxrAy3J53AMXM8z51UU3xk8E5rBbVPp2AilY0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":202200},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"e1b87d347020c98ffb1376dbe8ce8aef7c5136a9","scripts":{"lint":"biome lint ./src ./tests","test":"bun test","build":"bun run build.ts","check":"biome check ./src ./tests","format":"biome format --write ./src ./tests","prepare":"simple-git-hooks","test:ci":"bun test --coverage --coverage-threshold=100","lint:fix":"biome lint --write ./src ./tests","check:fix":"biome check --write ./src ./tests","typecheck":"tsc --noEmit","format:check":"biome format ./src ./tests","test:coverage":"bun test --coverage","prepublishOnly":"bun run typecheck && bun run check && bun run test:ci && bun run build"},"_npmUser":{"name":"carllee1983","email":"yashino538@gmail.com"},"repository":{"url":"git+https://github.com/CarlLee1983/tappay-backend-payment-node.git","type":"git"},"_npmVersion":"10.8.2","description":"TapPay Backend Payment SDK for Node.js - A TypeScript SDK for TapPay Backend Payment APIs with full type support","directories":{},"lint-staged":{"*.test.{ts,tsx}":["bun test --bail"],"*.{js,ts,cjs,mjs}":["biome check --write","bash -c 'bun run typecheck'"]},"_nodeVersion":"20.19.6","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.9.3","lint-staged":"^16.2.7","@biomejs/biome":"^2.3.8","simple-git-hooks":"^2.13.1"},"simple-git-hooks":{"pre-commit":"export PATH=\"$HOME/.bun/bin:$PATH\" && bun run test && bunx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/tappay-backend-payment-node_1.7.0_1765978317518_0.37399363966749966","host":"s3://npm-registry-packages-npm-production"}},"1.8.0":{"name":"@carllee1983/tappay-backend-payment-node","version":"1.8.0","keywords":["tappay","payment","payment-gateway","credit-card","debit-card","3d-secure","apple-pay","google-pay","line-pay","jkopay","taiwan","fintech","e-commerce","sdk","typescript","nodejs"],"author":{"name":"Carl Lee","email":"carllee1983@gmail.com"},"license":"MIT","_id":"@carllee1983/tappay-backend-payment-node@1.8.0","maintainers":[{"name":"carllee1983","email":"yashino538@gmail.com"}],"homepage":"https://github.com/CarlLee1983/tappay-backend-payment-node#readme","bugs":{"url":"https://github.com/CarlLee1983/tappay-backend-payment-node/issues"},"dist":{"shasum":"07e7472abe41304c7dce088966f4bfc111cb01a6","tarball":"https://registry.npmjs.org/@carllee1983/tappay-backend-payment-node/-/tappay-backend-payment-node-1.8.0.tgz","fileCount":54,"integrity":"sha512-4Euu2CDb4JkDxZr0kPNo6F4AelqhF43+DQcCkT7eal6vg7P/+IvtiT4NMXxQy1ZvWboPUg7vVa8wVfesRUxsmw==","signatures":[{"sig":"MEQCIE7sPeVFwRNSeTRbpu2w9sapa41zgVz8D1tG3z13POitAiAxKTzwggzQWGVG4moXmFROQ3my8QPlOYUejptR9YN4vw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":302924},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"cfd651d1fab8b1280dfcab322e00d24f9a947e33","scripts":{"lint":"biome lint ./src ./tests","test":"bun test","build":"bun run build.ts","check":"biome check ./src ./tests","format":"biome format --write ./src ./tests","prepare":"simple-git-hooks","test:ci":"bun test --coverage --coverage-threshold=100","lint:fix":"biome lint --write ./src ./tests","check:fix":"biome check --write ./src ./tests","typecheck":"tsc --noEmit","format:check":"biome format ./src ./tests","test:coverage":"bun test --coverage","prepublishOnly":"bun run typecheck && bun run check && bun run test:ci && bun run build"},"_npmUser":{"name":"carllee1983","email":"yashino538@gmail.com"},"repository":{"url":"git+https://github.com/CarlLee1983/tappay-backend-payment-node.git","type":"git"},"_npmVersion":"10.9.2","description":"TapPay Backend Payment SDK for Node.js - A TypeScript SDK for TapPay Backend Payment APIs with full type support","directories":{},"lint-staged":{"*.test.{ts,tsx}":["bun test --bail"],"*.{js,ts,cjs,mjs}":["biome check --write","bash -c 'bun run typecheck'"]},"_nodeVersion":"22.17.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"1.3.11","typescript":"^6.0.2","lint-staged":"^16.4.0","@biomejs/biome":"^2.4.8","simple-git-hooks":"^2.13.1"},"simple-git-hooks":{"pre-commit":"export PATH=\"$HOME/.bun/bin:$PATH\" && bun run test && bunx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/tappay-backend-payment-node_1.8.0_1774341578637_0.25498957063941163","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-12-12T17:24:16.242Z","modified":"2026-09-15T02:54:45.883Z","1.3.0":"2025-12-12T17:24:16.462Z","1.3.1":"2025-12-12T17:32:51.893Z","1.6.0":"2025-12-13T04:19:01.424Z","1.7.0":"2025-12-17T13:31:57.674Z","1.8.0":"2026-03-24T08:39:38.785Z"},"bugs":{"url":"https://github.com/CarlLee1983/tappay-backend-payment-node/issues"},"author":{"name":"Carl Lee","email":"carllee1983@gmail.com"},"license":"MIT","homepage":"https://github.com/CarlLee1983/tappay-backend-payment-node#readme","keywords":["tappay","payment","payment-gateway","credit-card","debit-card","3d-secure","apple-pay","google-pay","line-pay","jkopay","taiwan","fintech","e-commerce","sdk","typescript","nodejs"],"repository":{"url":"git+https://github.com/CarlLee1983/tappay-backend-payment-node.git","type":"git"},"description":"TapPay Backend Payment SDK for Node.js - A TypeScript SDK for TapPay Backend Payment APIs with full type support","maintainers":[{"email":"yashino538@gmail.com","name":"praxisbound"}],"readme":"# TapPay Backend Payment SDK\n\n[English](./README.md) | [繁體中文](./README_zh-TW.md)\n\n> A TypeScript SDK for TapPay Backend Payment APIs\n\n[![npm version](https://img.shields.io/npm/v/@carllee1983/tappay-backend-payment-node-node.svg)](https://www.npmjs.com/package/@carllee1983/tappay-backend-payment-node-node)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js->=18.0.0-green.svg)](https://nodejs.org/)\n\n## Features\n\n- 🔒 **Full TypeScript Support** - Complete type definitions for all APIs\n- 🚀 **Modern Architecture** - Built with ES Modules and CommonJS support\n- ⚡ **Zero Dependencies** - Uses native `fetch` API (Node.js 18+)\n- 🛡️ **Error Handling** - Typed error classes for precise error handling\n- 📦 **Small Bundle Size** - Minimal footprint for production use\n\n## Installation\n\n```bash\nnpm install @carllee1983/tappay-backend-payment-node-node\n# or\nyarn add @carllee1983/tappay-backend-payment-node-node\n# or\npnpm add @carllee1983/tappay-backend-payment-node-node\n# or\nbun add @carllee1983/tappay-backend-payment-node-node\n```\n\n## Quick Start\n\n```typescript\nimport { TapPayClient, Env, Currency } from '@carllee1983/tappay-backend-payment-node-node'\n\n// Create client\nconst client = new TapPayClient({\n  partnerKey: 'your_partner_key',\n  merchantId: 'your_merchant_id',\n  env: Env.Sandbox, // Use Env.Production for production\n})\n\n// Pay by Prime\nconst payment = await client.payByPrime({\n  prime: 'prime_from_frontend',\n  amount: 100,\n  currency: Currency.TWD,\n  details: 'Product Description',\n  cardholder: {\n    phone_number: '+886912345678',\n    name: 'Test User',\n    email: 'test@example.com',\n  },\n})\n\nconsole.log(`Transaction ID: ${payment.rec_trade_id}`)\n```\n\n## API Reference\n\n### TapPayClient\n\nThe main client class for interacting with TapPay APIs.\n\n#### Constructor\n\n```typescript\nnew TapPayClient({\n  partnerKey: string,   // Required: Partner Key from TapPay Portal\n  merchantId: string,   // Required: Merchant ID\n  env?: Env,            // Optional: Env.Sandbox (default) or Env.Production\n  timeout?: number,     // Optional: Request timeout in ms (default: 30000)\n})\n```\n\n### Payment Methods\n\n#### Pay by Prime\n\nProcess a payment using a prime token from frontend SDK.\n\n```typescript\nconst response = await client.payByPrime({\n  prime: 'test_prime_123',\n  amount: 100,\n  currency: Currency.TWD,\n  details: 'Test Payment',\n  cardholder: {\n    phone_number: '+886912345678',\n    name: 'Test User',\n    email: 'test@example.com',\n  },\n  // Optional: Enable 3D Secure\n  three_domain_secure: true,\n  result_url: {\n    frontend_redirect_url: 'https://example.com/payment/success',\n    backend_notify_url: 'https://example.com/api/notify',\n  },\n  // Optional: Remember card for future payments\n  remember: true,\n})\n\n// If remember=true, save these for future payments\nif (response.card_secret) {\n  const { card_key, card_token } = response.card_secret\n  // Store securely for recurring payments\n}\n```\n\n#### Pay by Card Token\n\nProcess a payment using saved card credentials.\n\n```typescript\nconst response = await client.payByToken({\n  card_key: 'saved_card_key',\n  card_token: 'saved_card_token',\n  amount: 100,\n  currency: Currency.TWD,\n  details: 'Recurring Payment',\n})\n```\n\n### Transaction Management\n\n#### Refund\n\nProcess a full or partial refund.\n\n```typescript\n// Full refund\nawait client.refund('D20231201123456789')\n\n// Partial refund\nawait client.refund('D20231201123456789', { amount: 50 })\n```\n\n#### Query Records\n\nRetrieve transaction records with filtering and pagination.\n\n```typescript\nconst records = await client.getRecords({\n  records_per_page: 10,\n  page: 0,\n  filters: {\n    time: {\n      start_time: Date.now() - 7 * 24 * 60 * 60 * 1000, // Last 7 days\n      end_time: Date.now(),\n    },\n  },\n  order_by: {\n    attribute: 'time',\n    is_descending: true,\n  },\n})\n```\n\n#### Get Single Transaction\n\n```typescript\nconst record = await client.getTransaction('D20231201123456789')\nif (record) {\n  console.log(`Status: ${record.status}`)\n}\n```\n\n#### Get Trade History\n\nGet detailed transaction history including all events.\n\n```typescript\nconst history = await client.getTradeHistory('D20231201123456789')\nhistory.trade_history?.forEach(event => {\n  console.log(`${event.event_type}: ${event.status}`)\n})\n```\n\n### Advanced APIs\n\n#### Capture Today\n\nCapture a delayed-capture transaction immediately.\n\n```typescript\nawait client.capToday('D20231201123456789')\n```\n\n#### Cancel Capture\n\nCancel a pending capture before bank batch processing.\n\n```typescript\nawait client.cancelCapture('D20231201123456789')\n```\n\n#### Cancel Refund\n\nCancel a pending refund (currently only supported by Taishin Bank).\n\n```typescript\nawait client.cancelRefund('D20231201123456789', 'R20231201123456789')\n```\n\n### Card Management\n\n#### Bind Card\n\nBind a card for future token-based payments without charging.\n\n```typescript\nconst response = await client.bindCard({\n  prime: 'prime_from_frontend',\n  currency: Currency.TWD,\n  cardholder: {\n    phone_number: '+886912345678',\n    name: 'Test User',\n    email: 'test@example.com'\n  }\n})\n\nif (response.card_secret) {\n  const { card_key, card_token } = response.card_secret\n  // Store for future payments\n}\n```\n\n#### Remove Card\n\nRemove a bound card from TapPay servers.\n\n```typescript\nawait client.removeCard('card_key_123', 'card_token_123')\n```\n\n## Error Handling\n\nThe SDK provides typed error classes for precise error handling. All errors extend the standard `Error` class and can be caught using try-catch blocks.\n\n### Error Types\n\n#### TapPayError\nThrown when the TapPay API returns an error response (e.g., invalid prime, insufficient funds, card declined).\n\n```typescript\nimport { TapPayError } from '@carllee1983/tappay-backend-payment-node'\n\ntry {\n  const response = await client.payByPrime({ ... })\n} catch (error) {\n  if (error instanceof TapPayError) {\n    console.error(`API Error: ${error.message}`)\n    console.error(`Status Code: ${error.status}`)\n    console.error(`Transaction ID: ${error.recTradeId}`)\n    \n    // Check if transaction failed\n    if (error.isTransactionFailed) {\n      // Handle failed transaction\n    }\n  }\n}\n```\n\n**Common TapPay Error Status Codes:**\n- `10001`: Invalid prime\n- `10002`: Invalid card number\n- `10003`: Insufficient funds\n- `10004`: Card declined\n- See [TapPay Documentation](https://docs.tappaysdk.com/tutorial/zh/reference.html#error-code) for complete list\n\n#### TapPayValidationError\nThrown when input validation fails before making the API request (e.g., missing required fields, invalid values).\n\n```typescript\nimport { TapPayValidationError } from '@carllee1983/tappay-backend-payment-node'\n\ntry {\n  await client.payByPrime({\n    prime: '', // Empty prime will trigger validation error\n    amount: 100,\n  })\n} catch (error) {\n  if (error instanceof TapPayValidationError) {\n    console.error(`Validation Error: ${error.message}`)\n    console.error(`Field: ${error.field}`) // e.g., 'prime', 'amount'\n  }\n}\n```\n\n**Common Validation Errors:**\n- Missing required fields (prime, amount, currency, etc.)\n- Empty strings for required fields\n- Invalid amount (zero or negative)\n- Empty transaction IDs\n\n#### TapPayTimeoutError\nThrown when the API request times out.\n\n```typescript\nimport { TapPayTimeoutError } from '@carllee1983/tappay-backend-payment-node'\n\ntry {\n  await client.payByPrime({ ... })\n} catch (error) {\n  if (error instanceof TapPayTimeoutError) {\n    console.error(`Request timed out after ${error.timeout}ms`)\n    console.error(`Endpoint: ${error.endpoint}`)\n    \n    // Consider retrying the request\n  }\n}\n```\n\n#### TapPayConfigError\nThrown when client configuration is invalid (e.g., missing partner key, invalid timeout).\n\n```typescript\nimport { TapPayConfigError } from '@carllee1983/tappay-backend-payment-node'\n\ntry {\n  const client = new TapPayClient({\n    partnerKey: '', // Empty key will trigger config error\n    merchantId: 'test_merchant_id',\n  })\n} catch (error) {\n  if (error instanceof TapPayConfigError) {\n    console.error(`Config Error: ${error.message}`)\n    console.error(`Field: ${error.field}`) // e.g., 'partnerKey', 'merchantId'\n  }\n}\n```\n\n### Complete Error Handling Example\n\n```typescript\nimport {\n  TapPayClient,\n  TapPayError,\n  TapPayConfigError,\n  TapPayTimeoutError,\n  TapPayValidationError,\n} from '@carllee1983/tappay-backend-payment-node'\n\nasync function processPayment(prime: string, amount: number) {\n  try {\n    const response = await client.payByPrime({\n      prime,\n      amount,\n      currency: Currency.TWD,\n      details: 'Product Purchase',\n    })\n    \n    return { success: true, transactionId: response.rec_trade_id }\n  } catch (error) {\n    if (error instanceof TapPayValidationError) {\n      // Input validation failed - fix the input and retry\n      console.error(`Invalid input: ${error.field} - ${error.message}`)\n      return { success: false, error: 'INVALID_INPUT', field: error.field }\n    } else if (error instanceof TapPayTimeoutError) {\n      // Request timed out - consider retrying\n      console.error(`Request timeout: ${error.endpoint}`)\n      return { success: false, error: 'TIMEOUT', retryable: true }\n    } else if (error instanceof TapPayError) {\n      // API returned an error\n      console.error(`Payment failed: ${error.message} (Status: ${error.status})`)\n      return {\n        success: false,\n        error: 'PAYMENT_FAILED',\n        status: error.status,\n        transactionId: error.recTradeId,\n      }\n    } else {\n      // Unexpected error\n      console.error('Unexpected error:', error)\n      return { success: false, error: 'UNKNOWN' }\n    }\n  }\n}\n```\n\n### Error Handling Best Practices\n\n1. **Always handle errors**: Wrap API calls in try-catch blocks\n2. **Check error types**: Use `instanceof` to handle different error types appropriately\n3. **Log errors**: Include error details in logs for debugging\n4. **Retry timeouts**: Consider retrying on `TapPayTimeoutError`\n5. **Validate input**: Catch `TapPayValidationError` early to provide better user feedback\n\n## Backend Notify\n\nFor 3D Secure and e-payment transactions, TapPay will POST to your `backend_notify_url`:\n\n```typescript\nimport type { BackendNotifyPayload } from '@carllee1983/tappay-backend-payment-node'\n\n// Express.js example\napp.post('/api/notify', (req, res) => {\n  const payload: BackendNotifyPayload = req.body\n\n  if (payload.status === 0) {\n    // Payment successful\n    console.log(`Transaction ${payload.rec_trade_id} completed`)\n  } else {\n    // Payment failed\n    console.log(`Transaction failed: ${payload.msg}`)\n  }\n\n  res.status(200).send('OK')\n})\n```\n\n## Currency Support\n\nThe SDK supports multiple currencies:\n\n```typescript\nimport { Currency, CurrencyMultiplier } from '@carllee1983/tappay-backend-payment-node'\n\nCurrency.TWD // Taiwan Dollar (multiplier: 1)\nCurrency.USD // US Dollar (multiplier: 100)\nCurrency.JPY // Japanese Yen (multiplier: 1)\nCurrency.EUR // Euro (multiplier: 100)\n// ... and more\n```\n\n> **Note**: For currencies with multiplier of 100, the amount should be multiplied by 100.\n> For example, USD $1.00 should be sent as `amount: 100`.\n\n## Test Cards\n\nFor sandbox testing, use TapPay's test cards:\n- **Success**: `4242424242424242`\n- **Failed**: `4111111111111111`\n\nSee [TapPay Documentation](https://docs.tappaysdk.com/tutorial/zh/reference.html#test-card) for more test cards.\n\n## Requirements\n\n- Node.js >= 18.0.0 (for native fetch support)\n- TypeScript >= 5.0 (for development)\n\n## License\n\nMIT © Carl Lee\n\n## Related\n\n- [TapPay Documentation](https://docs.tappaysdk.com/)\n- [TapPay Portal](https://www.tappaysdk.com/)\n","readmeFilename":"README.md"}