{"id":42511330,"url":"https://github.com/volverjs/satispay-node-sdk","last_synced_at":"2026-01-28T14:12:39.306Z","repository":{"id":327444461,"uuid":"1099324104","full_name":"volverjs/satispay-node-sdk","owner":"volverjs","description":"Satispay GBusiness API Node.js SDK","archived":false,"fork":false,"pushed_at":"2025-12-03T19:53:07.000Z","size":212,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2025-12-06T22:12:39.515Z","etag":null,"topics":["bun","deno","nodejs","payments","satispay","sdk"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@volverjs/satispay-node-sdk","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/volverjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-18T21:17:46.000Z","updated_at":"2025-12-03T19:58:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/volverjs/satispay-node-sdk","commit_stats":null,"previous_names":["volverjs/satispay-node-sdk"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/volverjs/satispay-node-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volverjs%2Fsatispay-node-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volverjs%2Fsatispay-node-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volverjs%2Fsatispay-node-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volverjs%2Fsatispay-node-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/volverjs","download_url":"https://codeload.github.com/volverjs/satispay-node-sdk/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volverjs%2Fsatispay-node-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28846058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T13:02:32.985Z","status":"ssl_error","status_checked_at":"2026-01-28T13:02:04.945Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","deno","nodejs","payments","satispay","sdk"],"created_at":"2026-01-28T14:12:38.531Z","updated_at":"2026-01-28T14:12:39.296Z","avatar_url":"https://github.com/volverjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# (Unofficial) Satispay GBusiness Node.js API SDK\n\n[![npm version](https://img.shields.io/npm/v/@volverjs/satispay-node-sdk.svg)](https://www.npmjs.com/package/@volverjs/satispay-node-sdk)\n[![codecov](https://codecov.io/gh/volverjs/satispay-node-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/volverjs/satispay-node-sdk)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-green.svg)](https://www.npmjs.com/package/@volverjs/satispay-node-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nUniversal (but unofficial) TypeScript SDK for Satispay GBusiness API integration. Zero external dependencies, compatible with Node.js, Deno, and Bun.\n\n## Features\n\n- **Zero dependencies** - Uses only native standard APIs (fetch, crypto)\n- **Multi-runtime** - Works with Node.js 18+, Deno 1.30+, and Bun 1.0+\n- **Lightweight** - Only 268KB bundle size\n- **Type-safe** - Complete TypeScript definitions\n- **Modern** - Fetch API, async/await, ES Modules\n- **Secure** - Native RSA-SHA256 encryption\n- **Developer-friendly** - Intuitive API with automatic conversions:\n  - 💶 Use `amount` (euros) instead of `amount_unit` (cents)\n  - 📅 Use `Date` objects instead of timestamp strings\n\n## Installation\n\n### Node.js\n\n```bash\nnpm install @volverjs/satispay-node-sdk\n```\n\n### Deno\n\n```typescript\nimport { Api, Payment } from \"npm:@volverjs/satispay-node-sdk\";\n```\n\nOr use `deno.json`:\n\n```json\n{\n  \"imports\": {\n    \"satispay\": \"npm:@volverjs/satispay-node-sdk\"\n  }\n}\n```\n\n### Bun\n\n```bash\nbun add @volverjs/satispay-node-sdk\n```\n\n## Quick Start\n\n### Authentication\n\nGet your credentials using the CLI tool with an activation token:\n\n```bash\nnpx @volverjs/satispay-node-sdk YOUR_ACTIVATION_TOKEN\n```\n\nThis will generate:\n- **Public Key** - RSA public key\n- **Private Key** - RSA private key (keep this secure!)\n- **Key ID** - Your authentication key ID\n\n**Where to get the activation token:**\n- **Production**: [Satispay Business Dashboard](https://business.satispay.com) → Developers → Generate Activation Code\n- **Sandbox**: Request from [Satispay Developer Support](https://developers.satispay.com/docs/credentials#sandbox-account)\n\n**Options:**\n```bash\nnpx @volverjs/satispay-node-sdk YOUR_TOKEN              # Sandbox (default)\nnpx @volverjs/satispay-node-sdk YOUR_TOKEN --production # Production\nnpx @volverjs/satispay-node-sdk YOUR_TOKEN --sandbox    # Sandbox (explicit)\n```\n\n\u003e **⚠️ Important**: The activation token is single-use. Save the generated credentials securely!\n\n### Configure the SDK\n\nUse the generated credentials to configure the SDK:\n\n```typescript\nimport { Api } from '@volverjs/satispay-node-sdk';\n\nApi.setSandbox(true); // or false for production\nApi.setPublicKey(process.env.SATISPAY_PUBLIC_KEY!);\nApi.setPrivateKey(process.env.SATISPAY_PRIVATE_KEY!);\nApi.setKeyId(process.env.SATISPAY_KEY_ID!);\n```\n\nStore credentials in `.env`:\n```bash\nSATISPAY_PUBLIC_KEY=\"-----BEGIN PUBLIC KEY-----\\n...\"\nSATISPAY_PRIVATE_KEY=\"-----BEGIN PRIVATE KEY-----\\n...\"\nSATISPAY_KEY_ID=\"your-key-id\"\n```\n\n## API Reference\n\n### Payment Operations\n\n#### Create Payment\n\n```typescript\n// Using amount in euros (recommended)\nconst payment = await Payment.create({\n  flow: 'MATCH_CODE',\n  amount: 1.00, // Automatically converted to 100 cents\n  currency: 'EUR',\n  callback_url: 'https://your-site.com/callback',\n  external_code: 'ORDER-123',\n  metadata: { order_id: '12345' },\n});\n\n// Or using amount_unit in cents (still supported)\nconst payment2 = await Payment.create({\n  flow: 'MATCH_CODE',\n  amount_unit: 100, // Amount in cents\n  currency: 'EUR',\n  callback_url: 'https://your-site.com/callback',\n  external_code: 'ORDER-123',\n  metadata: { order_id: '12345' },\n});\n```\n\n**💡 Tip**: Use `amount` (euros) for more intuitive code. The SDK automatically converts it to cents.\n\nSee [examples/create-payment-with-amount.ts](./examples/create-payment-with-amount.ts) for more examples.\n\n#### Get Payment\n\n```typescript\nconst payment = await Payment.get('PAYMENT_ID');\nconsole.log('Status:', payment.status);\n```\n\n#### List Payments\n\n```typescript\nconst result = await Payment.all({\n  limit: 20,\n  status: 'ACCEPTED',\n  from_date: '2024-01-01',\n});\n\nresult.data.forEach(payment =\u003e {\n  console.log(`${payment.id}: ${payment.status}`);\n});\n```\n\n##### Filter by Date\n\nYou can filter payments using `Date` objects or timestamp strings:\n\n```typescript\n// Using Date objects (recommended)\nconst yesterday = new Date();\nyesterday.setDate(yesterday.getDate() - 1);\n\nconst recentPayments = await Payment.all({\n  starting_after_timestamp: yesterday, // Date is automatically converted to milliseconds\n  limit: 10,\n});\n\n// Or using timestamp string (milliseconds)\nconst timestampString = new Date('2024-01-01').getTime().toString();\nconst paymentsFromDate = await Payment.all({\n  starting_after_timestamp: timestampString,\n  limit: 10,\n});\n```\n\nSee [examples/payment-date-filtering.ts](./examples/payment-date-filtering.ts) for more examples.\n\n#### Update Payment\n\n```typescript\n// Using amount in euros\nconst payment = await Payment.update('PAYMENT_ID', {\n  action: 'ACCEPT',\n  amount: 5.50, // Automatically converted to 550 cents\n});\n\n// Or using amount_unit in cents\nconst payment2 = await Payment.update('PAYMENT_ID', {\n  action: 'ACCEPT',\n  amount_unit: 550,\n});\n```\n\n### Consumer Operations\n\n```typescript\nimport { Consumer } from '@volverjs/satispay-node-sdk';\n\nconst consumer = await Consumer.get('+393331234567');\nconsole.log('Consumer:', consumer.name);\n```\n\n### Daily Closure\n\n```typescript\nimport { DailyClosure } from '@volverjs/satispay-node-sdk';\n\n// Today's closure\nconst closure = await DailyClosure.get();\n\n// Specific date using Date object (recommended)\nconst yesterday = new Date();\nyesterday.setDate(yesterday.getDate() - 1);\nconst closureByDate = await DailyClosure.get(yesterday);\n\n// Or using YYYYMMDD string format\nconst closureByString = await DailyClosure.get('20240115');\n\nconsole.log('Date:', closure.shop_daily_closure.id);\nconsole.log('Total:', closure.shop_daily_closure.amount_unit / 100, closure.shop_daily_closure.currency);\nconsole.log('Gross:', closure.shop_daily_closure.gross_amount_unit / 100);\nconsole.log('Refunds:', closure.shop_daily_closure.refund_amount_unit / 100);\n```\n\n### Pre-Authorized Payment Tokens\n\nPre-Authorized Payment Tokens allow consumers to authorize payments in advance:\n\n```typescript\nimport { PreAuthorizedPaymentToken } from '@volverjs/satispay-node-sdk';\n\n// Create a pre-authorized payment token\nconst token = await PreAuthorizedPaymentToken.create({\n  reason: 'Subscription payment',\n  callback_url: 'https://your-site.com/callback',\n  redirect_url: 'https://your-site.com/success',\n});\n\nconsole.log('Token ID:', token.id);\nconsole.log('Token:', token.token);\nconsole.log('Status:', token.status); // PENDING\n\n// Get token details\nconst retrievedToken = await PreAuthorizedPaymentToken.get(token.id);\n\n// Update token (e.g., cancel it)\nconst updatedToken = await PreAuthorizedPaymentToken.update(token.id, {\n  status: 'CANCELED',\n});\n\n// Once the consumer accepts the token, you can use it to create payments:\nconst payment = await Payment.create({\n  flow: 'PRE_AUTHORIZED',\n  token: token.token,\n  amount: 9.99,\n  currency: 'EUR',\n});\n```\n\n**Important Notes:**\n- The consumer must accept the token before it can be used for payments\n- Token status can be: `PENDING`, `ACCEPTED`, or `CANCELED`\n- Use the `token` field (not the `id`) when creating pre-authorized payments\n\n### Reports\n\n\u003e **⚠️ Special Authentication Required**: Report APIs require special authentication keys. Contact tech@satispay.com to enable access.\n\n```typescript\nimport { Report } from '@volverjs/satispay-node-sdk';\n\n// Create a new report\nconst report = await Report.create({\n  type: 'PAYMENT_FEE',\n  format: 'CSV', // or 'PDF', 'XLSX'\n  from_date: '2025-11-01',\n  to_date: '2025-11-30',\n  columns: ['transaction_id', 'transaction_date', 'total_amount'], // Optional\n});\n\n// Get list of reports\nconst reports = await Report.all({\n  limit: 10,\n  starting_after: 'report-123',\n});\n\n// Get specific report\nconst reportDetails = await Report.get('report-123');\n\nif (reportDetails.status === 'READY' \u0026\u0026 reportDetails.download_url) {\n  console.log('Download URL:', reportDetails.download_url);\n}\n```\n\n**Important Notes:**\n- Reports are extracted at merchant level (includes all shops)\n- Reports for the previous day should be generated at least 4 hours after midnight\n- Report status: `PENDING`, `READY`, or `FAILED`\n\n### Sessions (POS Integration)\n\nSessions are used for POS/device integration to manage fund lock payments incrementally:\n\n```typescript\nimport { Session } from '@volverjs/satispay-node-sdk';\n\n// Open a session from a fund lock\nconst session = await Session.open({\n  fund_lock_id: 'payment-fund-lock-123',\n});\n\nconsole.log('Session ID:', session.id);\nconsole.log('Available amount:', session.residual_amount_unit);\n\n// Add items to the session\nawait Session.createEvent(session.id, {\n  operation: 'ADD',\n  amount_unit: 500,\n  currency: 'EUR',\n  description: 'Coffee',\n  metadata: { sku: 'COFFEE-001' },\n});\n\n// Remove items (e.g., discount)\nawait Session.createEvent(session.id, {\n  operation: 'REMOVE',\n  amount_unit: 200,\n  currency: 'EUR',\n  description: 'Discount',\n});\n\n// Get session details\nconst details = await Session.get(session.id);\nconsole.log('Residual amount:', details.residual_amount_unit);\n\n// Close the session\nconst closedSession = await Session.update(session.id, {\n  status: 'CLOSE',\n});\n```\n\n### Meal Voucher \u0026 Fringe Benefits\n\nMeal Voucher and Fringe Benefits payments use the same `Payment` API with additional parameters:\n\n```typescript\nimport { Payment } from '@volverjs/satispay-node-sdk';\n\n// Create payment with Meal Voucher limits\nconst payment = await Payment.create({\n  flow: 'MATCH_CODE',\n  amount: 50.00,\n  currency: 'EUR',\n  meal_voucher_max_amount_unit: 4000, // Max 40 EUR with meal vouchers\n  meal_voucher_max_quantity: 8, // Max 8 vouchers\n});\n\n// Update payment with Meal Voucher limits\nconst updated = await Payment.update(payment.id, {\n  action: 'ACCEPT',\n  meal_voucher_max_amount_unit: 3000,\n  meal_voucher_max_quantity: 6,\n});\n```\n\n**Important Notes:**\n- Meal Vouchers and Fringe Benefits are mutually exclusive\n- Meal Voucher refunds: Only on the same day, full amount only\n- Fringe Benefits refunds: Only within the same month, full amount only\n- Default limit: 8 meal vouchers per payment if not specified\n\n## Runtime-Specific Examples\n\n### Node.js Server\n\n```typescript\nimport express from 'express';\nimport { Api, Payment } from '@volverjs/satispay-node-sdk';\n\nApi.setSandbox(true);\nApi.setPublicKey(process.env.SATISPAY_PUBLIC_KEY);\nApi.setPrivateKey(process.env.SATISPAY_PRIVATE_KEY);\nApi.setKeyId(process.env.SATISPAY_KEY_ID);\n\nconst app = express();\napp.use(express.json());\n\napp.post('/create-payment', async (req, res) =\u003e {\n  const payment = await Payment.create({\n    flow: 'MATCH_CODE',\n    amount_unit: req.body.amount,\n    currency: 'EUR',\n  });\n  res.json(payment);\n});\n\napp.listen(3000);\n```\n\n### Deno Server\n\n```typescript\nimport { serve } from \"https://deno.land/std@0.208.0/http/server.ts\";\nimport { Api, Payment } from \"npm:@volverjs/satispay-node-sdk\";\n\nApi.setSandbox(true);\nApi.setPublicKey(Deno.env.get(\"SATISPAY_PUBLIC_KEY\")!);\nApi.setPrivateKey(Deno.env.get(\"SATISPAY_PRIVATE_KEY\")!);\nApi.setKeyId(Deno.env.get(\"SATISPAY_KEY_ID\")!);\n\nserve(async (req) =\u003e {\n  const url = new URL(req.url);\n  \n  if (url.pathname === \"/create-payment\" \u0026\u0026 req.method === \"POST\") {\n    const body = await req.json();\n    const payment = await Payment.create({\n      flow: \"MATCH_CODE\",\n      amount_unit: body.amount,\n      currency: \"EUR\",\n    });\n    return Response.json(payment);\n  }\n  \n  return Response.json({ error: \"Not found\" }, { status: 404 });\n});\n```\n\n### Bun Server\n\n```typescript\nimport { Api, Payment } from \"@volverjs/satispay-node-sdk\";\n\nApi.setSandbox(true);\nApi.setPublicKey(process.env.SATISPAY_PUBLIC_KEY!);\nApi.setPrivateKey(process.env.SATISPAY_PRIVATE_KEY!);\nApi.setKeyId(process.env.SATISPAY_KEY_ID!);\n\nBun.serve({\n  port: 3000,\n  async fetch(req) {\n    const url = new URL(req.url);\n    \n    if (url.pathname === \"/create-payment\" \u0026\u0026 req.method === \"POST\") {\n      const body = await req.json();\n      const payment = await Payment.create({\n        flow: \"MATCH_CODE\",\n        amount_unit: body.amount,\n        currency: \"EUR\",\n      });\n      return Response.json(payment);\n    }\n    \n    return Response.json({ error: \"Not found\" }, { status: 404 });\n  },\n});\n```\n\n## Custom Headers\n\n```typescript\nimport { Api, Request } from '@volverjs/satispay-node-sdk';\n\n// Global headers\nApi.setPlatformHeader('MyApp');\nApi.setPlatformVersionHeader('1.0.0');\nApi.setPluginNameHeader('my-plugin');\nApi.setPluginVersionHeader('2.0.0');\nApi.setTypeHeader('ONLINE_SHOP');\nApi.setTrackingHeader('tracking-code-123');\n\n// Per-request headers\nconst payment = await Payment.create(\n  {\n    flow: 'MATCH_CODE',\n    amount_unit: 100,\n    currency: 'EUR',\n  },\n  {\n    [Request.HEADER_TRACKING_CODE]: 'custom-tracking-code',\n    [Request.HEADER_IDEMPOTENCY_KEY]: 'unique-key-123',\n  }\n);\n```\n\n## Environment Configuration\n\n### Sandbox Mode\n\n```typescript\nApi.setSandbox(true); // Test environment\nApi.setSandbox(false); // Production environment\n```\n\n### Environment Variables\n\nStore your credentials securely:\n\n```bash\n# .env\nSATISPAY_PUBLIC_KEY=\"-----BEGIN PUBLIC KEY-----...\"\nSATISPAY_PRIVATE_KEY=\"-----BEGIN PRIVATE KEY-----...\"\nSATISPAY_KEY_ID=\"your-key-id\"\n```\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build\npnpm build\n\n# Watch mode\npnpm build:watch\n\n# Run tests\npnpm test\n\n# Watch tests\npnpm test:watch\n\n# Test with UI\npnpm test:ui\n\n# Coverage report\npnpm test:coverage\n\n# Lint\npnpm lint\n\n# Format\npnpm format\n```\n\n## Testing\n\nThis project uses [Vitest](https://vitest.dev/) for testing. The test suite includes:\n\n- **Unit tests** for all core modules (Api, Payment, Consumer, DailyClosure, etc.)\n- **RSA Service tests** for cryptographic operations\n- **Mock-based tests** for API interactions\n\nCurrent test coverage: **94.82%** (Statements: 93.83%, Branches: 89.65%, Functions: 100%, Lines: 95.8%)\n\nRun tests:\n```bash\npnpm test              # Run all tests\npnpm test:watch        # Watch mode for development\npnpm test:ui           # Interactive UI\npnpm test:coverage     # Generate coverage report\n```\n\n## Examples\n\nSee the [`examples/`](./examples) directory for complete examples:\n\n- `auth-with-token.ts` - Authentication with token\n- `create-payment.ts` - Create a payment\n- `get-payment.ts` - Get payment details\n- `get-payments.ts` - List payments\n- `get-consumer.ts` - Get consumer information\n- `get-daily-closure.ts` - Get daily closure\n\nTo run examples:\n\n```bash\nnpm install\nnpm run build\ncd examples\nnpx tsc\nnode dist/auth-with-token.js\n```\n\n## Requirements\n\n| Runtime | Minimum Version | Native fetch Support |\n|---------|----------------|---------------------|\n| Node.js | 18.0.0 | Yes |\n| Deno | 1.30.0 | Yes |\n| Bun | 1.0.0 | Yes |\n\nNo external dependencies required.\n\n## Technical Details\n\nThis SDK uses Web Standard APIs:\n\n- **fetch API** for HTTP requests (native in all supported runtimes)\n- **crypto module** for RSA-SHA256 signatures (Node.js crypto with compatibility layers for Deno/Bun)\n\nBenefits:\n- Same code works across all runtimes\n- No polyfills needed\n- Native performance\n- Future-proof\n\n## Why Zero Dependencies?\n\n- No third-party vulnerability risks\n- Minimal bundle size (268KB)\n- Fast installation\n- No dependency conflicts\n- Uses only standard APIs\n\n## Error Handling\n\n```typescript\ntry {\n  const payment = await Payment.create({\n    flow: 'MATCH_CODE',\n    amount_unit: 100,\n    currency: 'EUR',\n  });\n} catch (error) {\n  console.error('Payment creation failed:', error.message);\n}\n```\n\n## TypeScript Support\n\nFull TypeScript support with complete type definitions included:\n\n```typescript\nimport type {\n  PaymentCreate,\n  PaymentResponse,\n  ConsumerResponse,\n  DailyClosureResponse,\n} from '@volverjs/satispay-node-sdk';\n```\n\n## License\n\nMIT\n\n## Links\n\n- [API Documentation](https://developers.satispay.com)\n- [Business Dashboard](https://business.satispay.com)\n- [Satispay Website](https://www.satispay.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolverjs%2Fsatispay-node-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolverjs%2Fsatispay-node-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolverjs%2Fsatispay-node-sdk/lists"}