{"_id":"@ariejones/propay-sdk","_rev":"3-8c24b8f1995f4ff24f25823da4094169","name":"@ariejones/propay-sdk","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@ariejones/propay-sdk","version":"1.0.0","keywords":["propay","spi","payment","sdk"],"author":{"name":"ariejones"},"license":"MIT","_id":"@ariejones/propay-sdk@1.0.0","maintainers":[{"name":"ariejones","email":"arie.jones@indydatapartners.com"}],"dist":{"shasum":"fc2e80a38dc28471a70c76a5a0b5f2b1b630e7f1","tarball":"https://registry.npmjs.org/@ariejones/propay-sdk/-/propay-sdk-1.0.0.tgz","fileCount":14,"integrity":"sha512-2cir04SICTPrPhBNH2iTtKVf9GlR9DLrELLyEbDN9sR6Q+Bt9Uo9Y9pBENYi7SBKWNGpqufsldCTvYramuqG2Q==","signatures":[{"sig":"MEQCIBKWrZTdd/70gpG3Q6Iyr9E/SHXoMlUZ1dSC99crq4N7AiBlw25hMiI4yWids1JW6/pVlmnBgRZN9uufZhgfkgHG6g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":50440},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"ec9c3581d4578523d8a5a0f2c617828889638e65","scripts":{"lint":"biome check .","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","format":"biome format --write .","lint:fix":"biome check --write .","validate":"ts-node validate.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"ariejones","email":"arie.jones@indydatapartners.com"},"_npmVersion":"11.5.1","description":"TypeScript SDK for ProPay SPI integration","directories":{},"_nodeVersion":"24.6.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.0.0","@types/node":"^20.0.0","@biomejs/biome":"^1.9.4"},"_npmOperationalInternal":{"tmp":"tmp/propay-sdk_1.0.0_1767965453829_0.6351744898852683","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@ariejones/propay-sdk","version":"1.0.1","keywords":["propay","spi","payment","sdk"],"author":{"name":"ariejones"},"license":"MIT","_id":"@ariejones/propay-sdk@1.0.1","maintainers":[{"name":"ariejones","email":"arie.jones@indydatapartners.com"}],"dist":{"shasum":"1cd1319600437f7c67b647eef42af28dbcbf04b6","tarball":"https://registry.npmjs.org/@ariejones/propay-sdk/-/propay-sdk-1.0.1.tgz","fileCount":14,"integrity":"sha512-5Xpacqa1ZcplTqCXuhZebphN9GkoxH8wYYn2hgZZRYI5H8K9G2Fn4HBrKO8b8sdh7/xHqWu5vbTDhNxHpUw+ng==","signatures":[{"sig":"MEUCIQCphUdMu9Hh0sk3RuggteaHzYb8h64BQ5L8zARQVB8hSgIgRMA8fyYZgo9zHrAkih18SK+GZZoFu/0gBEqUvNPQ3aQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51828},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"ec9c3581d4578523d8a5a0f2c617828889638e65","scripts":{"lint":"biome check .","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","format":"biome format --write .","lint:fix":"biome check --write .","validate":"ts-node validate.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"ariejones","email":"arie.jones@indydatapartners.com"},"_npmVersion":"11.5.1","description":"TypeScript SDK for ProPay SPI integration","directories":{},"_nodeVersion":"24.6.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.0.0","@types/node":"^20.0.0","@biomejs/biome":"^1.9.4"},"_npmOperationalInternal":{"tmp":"tmp/propay-sdk_1.0.1_1767966136650_0.09264784462265463","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@ariejones/propay-sdk","version":"1.0.2","description":"TypeScript SDK for ProPay SPI integration","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build","lint":"biome check .","lint:fix":"biome check --write .","format":"biome format --write .","validate":"ts-node validate.ts","test":"echo \"Error: no test specified\" && exit 1"},"keywords":["propay","spi","payment","sdk"],"author":{"name":"ariejones"},"license":"MIT","publishConfig":{"access":"public"},"devDependencies":{"@biomejs/biome":"^1.9.4","@types/node":"^20.0.0","ts-node":"^10.9.2","typescript":"^5.0.0"},"dependencies":{},"_id":"@ariejones/propay-sdk@1.0.2","gitHead":"76294211fe7ea69fd84171ec18c47bb135c2539c","_nodeVersion":"24.6.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-w1VVA7pXhQGWGtahCgUQdE7BTEUuGPH/9M3vxdhnSfqvo0s8SM8r9rvrXAMNZ3/nS/YMfqoM4QhM4YVm5nnJDg==","shasum":"29df53615e08bc2ba2dbb0a02497bbfddf22c6fc","tarball":"https://registry.npmjs.org/@ariejones/propay-sdk/-/propay-sdk-1.0.2.tgz","fileCount":14,"unpackedSize":52319,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAL7ypqeVR+GqqT7jBav2/nNVFnF9JcnaBDYhWq8GDcJAiEAgF04CD8nHweX/OyJt6MtyAA134SS5oVYu5Cenp4ESyQ="}]},"_npmUser":{"name":"ariejones","email":"arie.jones@indydatapartners.com"},"directories":{},"maintainers":[{"name":"ariejones","email":"arie.jones@indydatapartners.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/propay-sdk_1.0.2_1767987353040_0.8609011151556227"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-09T13:30:53.678Z","modified":"2026-01-09T19:35:53.353Z","1.0.0":"2026-01-09T13:30:53.972Z","1.0.1":"2026-01-09T13:42:16.780Z","1.0.2":"2026-01-09T19:35:53.169Z"},"author":{"name":"ariejones"},"license":"MIT","keywords":["propay","spi","payment","sdk"],"description":"TypeScript SDK for ProPay SPI integration","maintainers":[{"name":"ariejones","email":"arie.jones@indydatapartners.com"}],"readme":"# ProPay SDK\n\nTypeScript SDK for ProPay SPI (Secure Payment Interface) integration. This library provides a simple interface for handling ProPay temporary tokens, encryption, and decryption of SPI responses.\n\n## ⚠️ Server-Side Only\n\n**This SDK can only be used in server-side environments.** It requires Node.js APIs (`crypto`, `Buffer`) that are not available in browsers. The SDK will throw an error if instantiated in a browser environment.\n\n### Supported Environments\n\n- ✅ Node.js applications\n- ✅ Next.js API routes\n- ✅ Next.js Server Components\n- ✅ Next.js Server Actions\n- ✅ Express.js routes\n- ✅ Other Node.js server frameworks\n\n### Not Supported\n\n- ❌ Browser/client-side code\n- ❌ React Client Components (use Server Actions or API routes instead)\n- ❌ Browser-based bundlers that target the browser\n\n## Installation\n\n```bash\nnpm install @ariejones/propay-sdk\n```\n\n## Usage\n\n### Complete Example\n\nHere's a complete example showing the full workflow:\n\n```typescript\nimport { ProPaySDK } from \"@ariejones/propay-sdk\";\n\nasync function example() {\n  // Initialize the SDK\n  const sdk = new ProPaySDK({\n    profileId: \"your-profile-id\",\n    primaryAccountNumber: \"your-account-number\",\n    environment: \"test\", // or 'prod'\n    certString: \"your-cert-string\",\n    termId: \"your-term-id\",\n  });\n\n  try {\n    // Step 1: Get a temporary token (you'll need to obtain this from your backend/ProPay)\n    // Note: createTempToken is a private method. You should obtain temp tokens through\n    // your backend service that has access to ProPay API credentials.\n    const tempToken = \"your-temp-token-here\"; // Obtain from your backend\n\n    // Step 2: Encrypt payment data using the temp token\n    const paymentData =\n      \"Action=Store&CardNumber=4111111111111111&ExpireDate=1225&CVV2=123\";\n    const encrypted = sdk.encrypt(tempToken, paymentData);\n    console.log(\"Encrypted Data:\", encrypted);\n\n    // Step 3: Create settings cipher for SPI configuration\n    // This method creates a temp token internally and encrypts the settings\n    const { tempToken, encryptedSettings } = await sdk.createSettingsCipher({\n      payerId: 123456,\n      paymentProcessType: \"CreditCard\",\n      processMethod: \"Always\",\n      paymentMethodStorageOption: \"Capture\",\n      currencyCode: \"USD\", // Optional, defaults to \"USD\"\n      amount: 100.0,\n      invoiceNumber: \"INV-001\",\n      returnUrl: \"https://yourapp.com/return\",\n    });\n    console.log(\"Temp Token:\", tempToken);\n    console.log(\"Settings Cipher:\", encryptedSettings);\n\n    // Step 4: After receiving encrypted response from ProPay SPI, process it\n    // Use the tempToken returned from createSettingsCipher to decrypt the response\n    const encryptedResponse = \"base64-encrypted-response-from-propay\";\n\n    // Option 1: Just decrypt (returns data even if errors exist)\n    const decrypted = sdk.decryptResponse(tempToken, encryptedResponse);\n    console.log(\"Decrypted Response:\");\n    console.log(\"  Payer ID:\", decrypted.PayerId);\n    console.log(\"  Payment Method ID:\", decrypted.PaymentMethodId);\n\n    // Option 2: Process and validate (throws error if response contains errors)\n    try {\n      const processed = sdk.processSpiResponse(tempToken, encryptedResponse);\n      console.log(\"Processed Response (no errors):\", processed);\n    } catch (error) {\n      console.error(\n        \"SPI Response Error:\",\n        error instanceof Error ? error.message : String(error)\n      );\n    }\n  } catch (error) {\n    console.error(\n      \"Error:\",\n      error instanceof Error ? error.message : String(error)\n    );\n  }\n}\n```\n\n### Basic Setup\n\n```typescript\nimport { ProPaySDK } from \"@ariejones/propay-sdk\";\n\n// Create SDK instance\nconst sdk = new ProPaySDK({\n  profileId: \"your-profile-id\",\n  primaryAccountNumber: \"your-account-number\",\n  environment: \"test\", // or 'prod'\n  certString: \"your-cert-string\",\n  termId: \"your-term-id\",\n});\n```\n\n### Encrypting Data\n\n```typescript\n// Encrypt content using the temporary token\n// Note: You'll need to obtain the temp token from your backend service\nconst tempToken = \"your-temp-token-here\"; // Obtain from your backend\nconst content = \"Action=Store&CardNumber=4111111111111111&ExpireDate=1225\";\nconst encrypted = sdk.encrypt(tempToken, content);\nconsole.log(\"Encrypted:\", encrypted);\n```\n\n### Creating Settings Cipher\n\n```typescript\n// Create encrypted settings cipher for SPI configuration\n// This method creates a temp token internally and encrypts the settings\nconst { tempToken, encryptedSettings } = await sdk.createSettingsCipher({\n  payerId: 123456,\n  paymentProcessType: \"CreditCard\",\n  processMethod: \"Always\",\n  paymentMethodStorageOption: \"Capture\",\n  currencyCode: \"USD\", // Optional, defaults to \"USD\"\n  amount: 100.0,\n  invoiceNumber: \"INV-001\",\n  returnUrl: \"https://yourapp.com/return\",\n});\nconsole.log(\"Temp Token:\", tempToken);\nconsole.log(\"Settings Cipher:\", encryptedSettings);\n```\n\n### Decrypting SPI Response\n\n```typescript\n// Decrypt response from ProPay SPI (returns data even if errors exist)\nconst tempToken = \"your-temp-token-here\"; // Obtain from your backend\nconst decrypted = sdk.decryptResponse(tempToken, encryptedMessage);\nconsole.log(\"Payer ID:\", decrypted.PayerId);\nconsole.log(\"Payment Method ID:\", decrypted.PaymentMethodId);\n```\n\n### Processing SPI Response\n\n```typescript\n// Process and validate SPI response (throws error if response contains errors)\nconst tempToken = \"your-temp-token-here\"; // Obtain from your backend\ntry {\n  const processed = sdk.processSpiResponse(tempToken, encryptedMessage);\n  console.log(\"Successfully processed:\", processed);\n} catch (error) {\n  console.error(\"SPI Response Error:\", error.message);\n}\n```\n\n## API Reference\n\n### ProPaySDK\n\nMain SDK class for ProPay SPI operations.\n\n#### Constructor\n\n```typescript\nnew ProPaySDK(config: ProPaySDKConfig)\n```\n\n**Parameters:**\n\n- `config.profileId` (string): Your ProPay profile ID\n- `config.primaryAccountNumber` (string): Your primary account number\n- `config.environment` ('test' | 'prod'): Environment to use\n- `config.certString` (string): Certification string\n- `config.termId` (string): Terminal ID\n\n#### Methods\n\n##### `decryptResponse(token: string, encryptedMessage: string): SPIData`\n\nDecrypts encrypted SPI response from ProPay. Returns the decrypted data even if errors are present.\n\n**Parameters:**\n\n- `token` (string): Temporary token used for encryption\n- `encryptedMessage` (string): Base64 encoded encrypted message\n\n**Returns:** Decrypted `SPIData` object\n\n##### `processSpiResponse(token: string, encryptedMessage: string): SPIData`\n\nProcesses and validates an encrypted SPI response from ProPay. Throws an error if the response contains any errors.\n\n**Parameters:**\n\n- `token` (string): Temporary token used for encryption\n- `encryptedMessage` (string): Base64 encoded encrypted message\n\n**Returns:** Decrypted and validated `SPIData` object\n\n**Throws:** Error if the response contains ErrCode, StoreErrCode, or ProcErrCode\n\n##### `createSettingsCipher(options: CreateSettingsCipherOptions): Promise<CreateSettingsCipherResult>`\n\nCreates a settings cipher (encrypted string) for SPI configuration. This method creates a temporary token internally and uses it to encrypt the settings.\n\n**Parameters:**\n\n- `options.payerId` (number): Payer ID for the transaction\n- `options.paymentProcessType` ('ACH' | 'CreditCard'): Type of payment processing\n- `options.processMethod` ('Always' | 'None' | 'OnSuccess'): Processing method\n- `options.paymentMethodStorageOption` ('None' | 'Capture' | 'AuthOnly'): Storage option for payment method\n- `options.currencyCode` (string, optional): Currency code, defaults to \"USD\"\n- `options.amount` (number): Transaction amount\n- `options.invoiceNumber` (string): Invoice number for the transaction\n- `options.returnUrl` (string): URL to return to after payment processing\n- `options.durationSeconds` (string, optional): Duration for the temporary token in seconds, defaults to \"3600\" (1 hour)\n\n**Returns:** Promise resolving to an object containing:\n\n- `tempToken` (string): The temporary token used for encryption\n- `encryptedSettings` (string): Base64 encoded encrypted settings string\n\n**Throws:** Error if required parameters are missing or if temporary token creation fails\n\n##### `getEndpoints(): Readonly<ProPayEndpoints>`\n\nGets all ProPay endpoints for the current environment.\n\n**Returns:** Readonly object containing all endpoint URIs\n\n##### `getSpiUrl(): string`\n\nGets the SPI (Secure Payment Interface) URL.\n\n**Returns:** SPI endpoint URL\n\n##### `getRestBaseUri(): string`\n\nGets the ProtectPay REST API base URI.\n\n**Returns:** REST API base URI\n\n##### `getSoapUri(): string`\n\nGets the ProtectPay SOAP URI.\n\n**Returns:** SOAP endpoint URI\n\n##### `getWsdlUri(): string`\n\nGets the ProtectPay WSDL URI.\n\n**Returns:** WSDL endpoint URI\n\n##### `getWsdlSingleFileUri(): string`\n\nGets the ProtectPay WSDL single file URI.\n\n**Returns:** WSDL single file endpoint URI\n\n## Types\n\n### SPIData\n\nDecrypted SPI response data structure containing payment method and transaction information.\n\n### CreateTempTokenResult\n\nTemporary token result from ProPay containing:\n\n- `tempToken`: Temporary token for SPI operations\n- `payerId`: Payer ID associated with the token\n- `credentialId`: Credential ID\n- `primaryBillingProfileId`: Primary billing profile ID\n- `practiceProfileId`: Practice profile ID\n\n### CreateSettingsCipherOptions\n\nOptions for creating a settings cipher:\n\n- `payerId` (number): Payer ID for the transaction\n- `paymentProcessType` ('ACH' | 'CreditCard'): Type of payment processing\n- `processMethod` ('Always' | 'None' | 'OnSuccess'): Processing method\n- `paymentMethodStorageOption` ('None' | 'Capture' | 'AuthOnly'): Storage option for payment method\n- `currencyCode` (string, optional): Currency code, defaults to \"USD\"\n- `amount` (number): Transaction amount\n- `invoiceNumber` (string): Invoice number for the transaction\n- `returnUrl` (string): URL to return to after payment processing\n- `durationSeconds` (string, optional): Duration for the temporary token in seconds, defaults to \"3600\"\n\n### CreateSettingsCipherResult\n\nResult from creating a settings cipher:\n\n- `tempToken` (string): The temporary token used for encryption\n- `encryptedSettings` (string): Base64 encoded encrypted settings string\n\n## Environment Configuration\n\nThe SDK automatically configures all ProPay endpoints based on the environment:\n\n### Test/Integration Environment\n\n- XML API: `https://xmltest.propay.com/API/PropayAPI.aspx`\n- SPI URL: `https://protectpaytest.propay.com/pmi/spr.aspx`\n- REST Base: `https://xmltestapi.propay.com/protectpay`\n- SOAP: `https://xmltestapi.propay.com/protectpay/sps.svc`\n- WSDL: `https://xmltestapi.propay.com/protectpay/sps.svc?wsdl`\n\n### Production Environment\n\n- XML API: `https://epay.propay.com/API/PropayAPI.aspx`\n- SPI URL: `https://protectpay.propay.com/pmi/spr.aspx`\n- REST Base: `https://api.propay.com/protectpay`\n- SOAP: `https://api.propay.com/protectpay/sps.svc`\n- WSDL: `https://api.propay.com/protectpay/sps.svc?wsdl`\n\nAll endpoints are accessible via the SDK instance methods (e.g., `sdk.getSpiUrl()`, `sdk.getRestBaseUri()`).\n\n## Error Handling\n\nAll methods throw errors with descriptive messages. Always wrap SDK calls in try-catch blocks:\n\n```typescript\ntry {\n  const encrypted = sdk.encrypt(tempToken, content);\n} catch (error) {\n  console.error(\"Encryption failed:\", error.message);\n}\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}