@networksolution/sia-vpos-node 1.0.0

package/README.md

@@ -0,0 +1,245 @@
+# sia-vpos-node
+
+Node.js SDK for **SIA/Nexi VPOS** payment gateway (API v2.4.3).
+
+Supports all major operations: Authorization, Pay-By-Link, Booking, Refund, and webhook verification.
+
+## Installation
+
+```bash
+npm install @networksolution/sia-vpos-node
+```
+
+## Quick Start
+
+```typescript
+import { VposClient } from '@networksolution/sia-vpos-node';
+
+const vpos = new VposClient({
+  shopId: '000000000000003',       // Merchant ID (15 chars)
+  operatorId: 'oper0001',          // Operator ID (8-18 chars)
+  secretKey: 'your_secret_string', // Shared secret (50 or 100 chars)
+  hashAlgorithm: 'hmac-sha256',   // 'hmac-sha256' (recommended) | 'sha1' | 'md5'
+  environment: 'test',             // 'test' (default) | 'production'
+});
+```
+
+## Environment (Test vs Production)
+
+The SDK defaults to the **test** environment for safety. Three ways to control it:
+
+**1. Config option (recommended):**
+```typescript
+// Test (default)
+const vpos = new VposClient({ ..., environment: 'test' });
+
+// Production
+const vpos = new VposClient({ ..., environment: 'production' });
+```
+
+**2. Environment variable `VPOS_ENV`:**
+```bash
+# .env or shell
+VPOS_ENV=test        # uses test URL
+VPOS_ENV=production  # uses production URL
+```
+```typescript
+// No need to specify environment - picks up VPOS_ENV automatically
+const vpos = new VposClient({ shopId, operatorId, secretKey });
+```
+
+**3. Custom URL (overrides everything):**
+```typescript
+const vpos = new VposClient({
+  ...,
+  apiUrl: 'https://custom-proxy.example.com/vpos',
+});
+```
+
+**Priority:** `apiUrl` > `environment` > `VPOS_ENV` > `'test'` (default)
+
+**Helper properties:**
+```typescript
+vpos.isTest;       // true if test environment
+vpos.isProduction; // true if production environment
+vpos.apiUrl;       // current API URL
+```
+
+| Environment | URL |
+|---|---|
+| **test** | `https://virtualpostest.sia.eu/vpos/apibo/apiBOXML-UTF8.app` |
+| **production** | `https://virtualpos.sia.eu/vpos/apibo/apiBOXML-UTF8.app` |
+
+## Operations
+
+### Authorization (Hosted Payment Page)
+
+Server-to-server card payment authorization.
+
+```typescript
+const result = await vpos.authorize({
+  orderId: 'ORDER-001',
+  pan: '9998500000000015',
+  expDate: '0409',       // yyMM
+  cvv2: '123',
+  amount: 4450,          // EUR 44.50 (in cents)
+  currency: '978',       // EUR
+  accountingMode: 'I',   // I=Immediate, D=Deferred
+  network: '01',         // 01=VISA, 02=MC, 93=auto
+});
+
+if (result.result === '00') {
+  console.log('Authorized!', result.authorization);
+}
+```
+
+### Pay-By-Link (Create Payment Link)
+
+```typescript
+const link = await vpos.createLink({
+  sendMail: 'Y',
+  linkAmount: 9900,                // EUR 99.00
+  linkOrderId: 'PBL-20260220-001',
+  linkUrlMs: 'https://yoursite.com/api/vpos/webhook',
+  linkUrlDone: 'https://yoursite.com/payment/success',
+  linkAccountingMode: 'I',
+  linkAuthorMode: 'I',
+  linkLang: 'EN',
+  linkName: 'John',
+  linkSurname: 'Doe',
+  linkEmail: 'john@example.com',
+});
+
+if (link.result === '00' && link.linkCreated) {
+  console.log('Payment link:', link.linkCreated.completeLink);
+  console.log('Token:', link.linkCreated.token);
+}
+```
+
+### List Links
+
+```typescript
+const links = await vpos.listLinks({
+  startDate: '2026-01-01',
+  endDate: '2026-12-31',
+  linkStatus: '01',  // optional filter
+});
+console.log('Found links:', links.links);
+```
+
+### Revoke Link
+
+```typescript
+await vpos.revokeLink({ token: 'scxfuyegan23510hi68vm7s12' });
+```
+
+### Booking / Capture (Accounting)
+
+Capture a deferred authorization.
+
+```typescript
+const capture = await vpos.accounting({
+  transactionId: '8032180310AB0E30917930112',
+  orderId: 'ORDER-001',
+  amount: 4450,
+});
+```
+
+### Reverse Accounting (Cancel Booking)
+
+```typescript
+await vpos.reverseAccounting({
+  transactionId: '8032180310AB0E30917930112',
+  orderId: 'ORDER-001',
+});
+```
+
+### Refund
+
+```typescript
+const refund = await vpos.refund({
+  transactionId: '8032180310AB0E30917930112',
+  orderId: 'ORDER-001',
+  amount: 2000, // partial refund EUR 20.00
+});
+```
+
+### Order Status
+
+```typescript
+const status = await vpos.orderStatus({ orderId: 'ORDER-001' });
+console.log('Authorization:', status.authorization);
+```
+
+## Webhook Verification
+
+When SIA sends server-to-server notifications (URLMS), verify the response MAC:
+
+```typescript
+// In your Express/Next.js webhook handler:
+app.post('/api/vpos/webhook', (req, res) => {
+  const xml = req.body; // raw XML string
+
+  // Parse the webhook data
+  const data = vpos.parseWebhook(xml);
+
+  // Verify root MAC (Timestamp + Result)
+  const isValid = vpos.verifyBPWResponseMAC(
+    data.timestamp,
+    data.result,
+    data.mac
+  );
+
+  if (!isValid) {
+    return res.status(400).send('Invalid MAC');
+  }
+
+  if (data.result === '00' && data.authorization) {
+    // Payment successful
+    console.log('Order:', data.authorization.orderId);
+    console.log('Amount:', data.authorization.authorizedAmount);
+  }
+
+  res.status(200).send('OK');
+});
+```
+
+## MAC Algorithms
+
+The SDK supports 3 hash algorithms (spec section 4.2):
+
+| Algorithm | MAC Length | Method |
+|---|---|---|
+| `md5` | 32 chars | `MD5(text + secretKey)` |
+| `sha1` | 40 chars | `SHA1(text + secretKey)` |
+| `hmac-sha256` | 64 chars | `HMAC-SHA256(text, secretKey)` **(recommended)** |
+
+## Result Codes
+
+| Code | Description |
+|---|---|
+| `00` | Success |
+| `02` | ReqRefNum duplicated or incorrect |
+| `03` | Incorrect message format |
+| `04` | Incorrect MAC / authentication |
+| `06` | Processing error |
+| `07` | TransactionID not found |
+| `13` | Duplicated order |
+| `99` | Transaction failed (see Data) |
+
+Full list available via `import { RESULT_CODES } from '@networksolution/sia-vpos-node'`.
+
+## Link Statuses
+
+| Code | Status |
+|---|---|
+| `00` | Created |
+| `01` | Returned |
+| `02` | Sent |
+| `03` | Used |
+| `04` | Paid |
+| `05` | Revoked |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { VposClient, generateTimestamp, generateReqRefNum } from './vpos-client';
+export { generateMAC, verifyMAC, computeHash } from './mac';
+export { buildBPWXmlRequest, buildHeaderXml, el, parseBPWXmlResponse, parseAuthorization, parsePanAliasData, parseOperation, parseLinkCreated, parseLinkCreatedList, getXmlValue, getXmlBlocks, } from './xml';
+export type { VposConfig, VposEnvironment, HashAlgorithm, HeaderData, AuthorizationRequest, AuthorizationResponse, PanAliasData, CreateLinkRequest, LinkCreatedData, ListLinkRequest, RevokeLinkRequest, AccountingRequest, ReverseAccountingRequest, RefundRequest, OrderStatusRequest, OperationData, VposResponse, } from './types';
+export { RESULT_CODES, LINK_STATUS } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC5D,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,EAAE,EACF,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,YAAY,GACb,MAAM,OAAO,CAAC;AACf,YAAY,EACV,UAAU,EACV,eAAe,EACf,aAAa,EACb,UAAU,EACV,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINK_STATUS = exports.RESULT_CODES = exports.getXmlBlocks = exports.getXmlValue = exports.parseLinkCreatedList = exports.parseLinkCreated = exports.parseOperation = exports.parsePanAliasData = exports.parseAuthorization = exports.parseBPWXmlResponse = exports.el = exports.buildHeaderXml = exports.buildBPWXmlRequest = exports.computeHash = exports.verifyMAC = exports.generateMAC = exports.generateReqRefNum = exports.generateTimestamp = exports.VposClient = void 0;
+var vpos_client_1 = require("./vpos-client");
+Object.defineProperty(exports, "VposClient", { enumerable: true, get: function () { return vpos_client_1.VposClient; } });
+Object.defineProperty(exports, "generateTimestamp", { enumerable: true, get: function () { return vpos_client_1.generateTimestamp; } });
+Object.defineProperty(exports, "generateReqRefNum", { enumerable: true, get: function () { return vpos_client_1.generateReqRefNum; } });
+var mac_1 = require("./mac");
+Object.defineProperty(exports, "generateMAC", { enumerable: true, get: function () { return mac_1.generateMAC; } });
+Object.defineProperty(exports, "verifyMAC", { enumerable: true, get: function () { return mac_1.verifyMAC; } });
+Object.defineProperty(exports, "computeHash", { enumerable: true, get: function () { return mac_1.computeHash; } });
+var xml_1 = require("./xml");
+Object.defineProperty(exports, "buildBPWXmlRequest", { enumerable: true, get: function () { return xml_1.buildBPWXmlRequest; } });
+Object.defineProperty(exports, "buildHeaderXml", { enumerable: true, get: function () { return xml_1.buildHeaderXml; } });
+Object.defineProperty(exports, "el", { enumerable: true, get: function () { return xml_1.el; } });
+Object.defineProperty(exports, "parseBPWXmlResponse", { enumerable: true, get: function () { return xml_1.parseBPWXmlResponse; } });
+Object.defineProperty(exports, "parseAuthorization", { enumerable: true, get: function () { return xml_1.parseAuthorization; } });
+Object.defineProperty(exports, "parsePanAliasData", { enumerable: true, get: function () { return xml_1.parsePanAliasData; } });
+Object.defineProperty(exports, "parseOperation", { enumerable: true, get: function () { return xml_1.parseOperation; } });
+Object.defineProperty(exports, "parseLinkCreated", { enumerable: true, get: function () { return xml_1.parseLinkCreated; } });
+Object.defineProperty(exports, "parseLinkCreatedList", { enumerable: true, get: function () { return xml_1.parseLinkCreatedList; } });
+Object.defineProperty(exports, "getXmlValue", { enumerable: true, get: function () { return xml_1.getXmlValue; } });
+Object.defineProperty(exports, "getXmlBlocks", { enumerable: true, get: function () { return xml_1.getXmlBlocks; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "RESULT_CODES", { enumerable: true, get: function () { return types_1.RESULT_CODES; } });
+Object.defineProperty(exports, "LINK_STATUS", { enumerable: true, get: function () { return types_1.LINK_STATUS; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6CAAiF;AAAxE,yGAAA,UAAU,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AACzD,6BAA4D;AAAnD,kGAAA,WAAW,OAAA;AAAE,gGAAA,SAAS,OAAA;AAAE,kGAAA,WAAW,OAAA;AAC5C,6BAYe;AAXb,yGAAA,kBAAkB,OAAA;AAClB,qGAAA,cAAc,OAAA;AACd,yFAAA,EAAE,OAAA;AACF,0GAAA,mBAAmB,OAAA;AACnB,yGAAA,kBAAkB,OAAA;AAClB,wGAAA,iBAAiB,OAAA;AACjB,qGAAA,cAAc,OAAA;AACd,uGAAA,gBAAgB,OAAA;AAChB,2GAAA,oBAAoB,OAAA;AACpB,kGAAA,WAAW,OAAA;AACX,mGAAA,YAAY,OAAA;AAqBd,iCAAoD;AAA3C,qGAAA,YAAY,OAAA;AAAE,oGAAA,WAAW,OAAA"}

package/dist/mac.d.ts

@@ -0,0 +1,26 @@
+import type { HashAlgorithm } from './types';
+/**
+ * Generate MAC hash using the specified algorithm.
+ *
+ * Per SIA VPOS spec:
+ * - SHA-1 and MD5: Hash(text + secretKey) — secret appended to string
+ * - HMAC-SHA256: HMAC(text, secretKey) — secret used as HMAC key, NOT appended
+ *
+ * The result is hex-encoded (lowercase).
+ * MD5 = 32 chars, SHA-1 = 40 chars, HMAC-SHA256 = 64 chars
+ */
+export declare function computeHash(text: string, secretKey: string, algorithm?: HashAlgorithm): string;
+/**
+ * Build MAC string from an ordered array of [KEY, VALUE] pairs.
+ * Optional fields that are undefined/null/empty are SKIPPED entirely (per spec).
+ * Format: KEY1=value1&KEY2=value2&...
+ *
+ * For SHA-1/MD5, the secret key is appended: ...&secretKey
+ * For HMAC-SHA256, the secret key is used as HMAC key (not in the string)
+ */
+export declare function generateMAC(fields: [string, string | number | undefined | null][], secretKey: string, algorithm?: HashAlgorithm): string;
+/**
+ * Verify a MAC received in a response.
+ */
+export declare function verifyMAC(fields: [string, string | number | undefined | null][], secretKey: string, receivedMac: string, algorithm?: HashAlgorithm): boolean;
+//# sourceMappingURL=mac.d.ts.map

package/dist/mac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mac.d.ts","sourceRoot":"","sources":["../src/mac.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAE,aAA6B,GAAG,MAAM,CAW7G;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,EAAE,EACtD,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,aAA6B,GACvC,MAAM,CAkBR;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,EAAE,EACtD,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,aAA6B,GACvC,OAAO,CAIT"}

package/dist/mac.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeHash = computeHash;
+exports.generateMAC = generateMAC;
+exports.verifyMAC = verifyMAC;
+const crypto_js_1 = __importDefault(require("crypto-js"));
+/**
+ * Generate MAC hash using the specified algorithm.
+ *
+ * Per SIA VPOS spec:
+ * - SHA-1 and MD5: Hash(text + secretKey) — secret appended to string
+ * - HMAC-SHA256: HMAC(text, secretKey) — secret used as HMAC key, NOT appended
+ *
+ * The result is hex-encoded (lowercase).
+ * MD5 = 32 chars, SHA-1 = 40 chars, HMAC-SHA256 = 64 chars
+ */
+function computeHash(text, secretKey, algorithm = 'hmac-sha256') {
+    switch (algorithm) {
+        case 'md5':
+            return crypto_js_1.default.MD5(text + secretKey).toString(crypto_js_1.default.enc.Hex);
+        case 'sha1':
+            return crypto_js_1.default.SHA1(text + secretKey).toString(crypto_js_1.default.enc.Hex);
+        case 'hmac-sha256':
+            return crypto_js_1.default.HmacSHA256(text, secretKey).toString(crypto_js_1.default.enc.Hex);
+        default:
+            throw new Error(`Unsupported hash algorithm: ${algorithm}`);
+    }
+}
+/**
+ * Build MAC string from an ordered array of [KEY, VALUE] pairs.
+ * Optional fields that are undefined/null/empty are SKIPPED entirely (per spec).
+ * Format: KEY1=value1&KEY2=value2&...
+ *
+ * For SHA-1/MD5, the secret key is appended: ...&secretKey
+ * For HMAC-SHA256, the secret key is used as HMAC key (not in the string)
+ */
+function generateMAC(fields, secretKey, algorithm = 'hmac-sha256') {
+    const parts = [];
+    for (const [key, value] of fields) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        parts.push(`${key}=${value}`);
+    }
+    const macString = parts.join('&');
+    if (algorithm === 'hmac-sha256') {
+        // HMAC-256: secret key is NOT appended; it's used as the HMAC key
+        return computeHash(macString, secretKey, algorithm);
+    }
+    else {
+        // SHA-1 / MD5: secret key IS appended to the string
+        // The computeHash function already handles this (text + secretKey)
+        return computeHash(macString, secretKey, algorithm);
+    }
+}
+/**
+ * Verify a MAC received in a response.
+ */
+function verifyMAC(fields, secretKey, receivedMac, algorithm = 'hmac-sha256') {
+    if (!receivedMac || receivedMac === 'NULL')
+        return false;
+    const computed = generateMAC(fields, secretKey, algorithm);
+    return computed.toLowerCase() === receivedMac.toLowerCase();
+}
+//# sourceMappingURL=mac.js.map

package/dist/mac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mac.js","sourceRoot":"","sources":["../src/mac.ts"],"names":[],"mappings":";;;;;AAaA,kCAWC;AAUD,kCAsBC;AAKD,8BASC;AAtED,0DAAiC;AAGjC;;;;;;;;;GASG;AACH,SAAgB,WAAW,CAAC,IAAY,EAAE,SAAiB,EAAE,YAA2B,aAAa;IACnG,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,KAAK;YACR,OAAO,mBAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC,QAAQ,CAAC,mBAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnE,KAAK,MAAM;YACT,OAAO,mBAAQ,CAAC,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC,QAAQ,CAAC,mBAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpE,KAAK,aAAa;YAChB,OAAO,mBAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,mBAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACzE;YACE,MAAM,IAAI,KAAK,CAAC,+BAA+B,SAAS,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,WAAW,CACzB,MAAsD,EACtD,SAAiB,EACjB,YAA2B,aAAa;IAExC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QAClC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;YAAE,SAAS;QACpE,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAElC,IAAI,SAAS,KAAK,aAAa,EAAE,CAAC;QAChC,kEAAkE;QAClE,OAAO,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IACtD,CAAC;SAAM,CAAC;QACN,oDAAoD;QACpD,mEAAmE;QACnE,OAAO,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,SAAS,CACvB,MAAsD,EACtD,SAAiB,EACjB,WAAmB,EACnB,YAA2B,aAAa;IAExC,IAAI,CAAC,WAAW,IAAI,WAAW,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACzD,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAC3D,OAAO,QAAQ,CAAC,WAAW,EAAE,KAAK,WAAW,CAAC,WAAW,EAAE,CAAC;AAC9D,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,268 @@
+export type HashAlgorithm = 'sha1' | 'md5' | 'hmac-sha256';
+export type VposEnvironment = 'test' | 'production';
+export interface VposConfig {
+    /** Merchant store identifier (MID) - 15 chars */
+    shopId: string;
+    /** Operator identifier (User ID) - 8-18 chars */
+    operatorId: string;
+    /** Shared secret string (50 or 100 chars) */
+    secretKey: string;
+    /** Hash algorithm: 'sha1' | 'md5' | 'hmac-sha256' (recommended) */
+    hashAlgorithm?: HashAlgorithm;
+    /** Environment: 'test' or 'production'. Defaults to 'test' for safety.
+     *  Can also be set via VPOS_ENV environment variable. */
+    environment?: VposEnvironment;
+    /** Custom API URL - overrides environment-based URL if provided */
+    apiUrl?: string;
+    /** Release version - defaults to '02' */
+    release?: string;
+}
+export interface HeaderData {
+    shopId: string;
+    operatorId: string;
+    reqRefNum: string;
+}
+export interface AuthorizationRequest {
+    /** Unique order identifier (1-50 chars) */
+    orderId: string;
+    /** Card number (PAN) - 10-19 chars */
+    pan: string;
+    /** Card expiry date - yyMM format */
+    expDate: string;
+    /** Amount in smallest currency unit (EUR cents) */
+    amount: number;
+    /** ISO currency code (978 = EUR) */
+    currency?: string;
+    /** Exponent of the currency */
+    exponent?: string;
+    /** Accounting mode: D=Deferred, I=Immediate */
+    accountingMode: 'D' | 'I';
+    /** Network code (01=VISA, 02=MasterCard, etc. 93=auto) */
+    network: string;
+    /** CVV2 code (optional) */
+    cvv2?: string;
+    /** Create PAN alias: S=DO, null=DON'T */
+    createPanAlias?: 'S';
+    /** Cardholder email */
+    emailCH?: string;
+    /** Cardholder identifier */
+    userId?: string;
+    /** Acquirer code */
+    acquirer?: string;
+    /** IP address */
+    ipAddress?: string;
+    /** Operation description (max 100) */
+    opDescr?: string;
+    /** User auth flag: 0=occasional, 1=registered, 2=unrecognized */
+    usrAuthFlag?: '0' | '1' | '2';
+    /** Additional options (max 26 chars) */
+    options?: string;
+    /** Antifraud payload */
+    antifraud?: string;
+    /** Sale identifier (max 15) */
+    productRef?: string;
+    /** Cardholder first name (max 40) */
+    name?: string;
+    /** Cardholder surname (max 40) */
+    surname?: string;
+    /** Cardholder tax ID (max 16) */
+    taxId?: string;
+    /** Recurring payment type: R, U, C */
+    tRecurr?: 'R' | 'U' | 'C';
+    /** Recurring code (max 50) */
+    cRecurr?: string;
+    /** Installments number (0-99) */
+    installmentsNumber?: string;
+}
+export interface AuthorizationResponse {
+    paymentType: string;
+    authorizationType: string;
+    transactionId: string;
+    network: string;
+    orderId: string;
+    transactionAmount: string;
+    authorizedAmount: string;
+    currency: string;
+    exponent: string;
+    accountedAmount: string;
+    refundedAmount: string;
+    transactionResult: string;
+    timestamp: string;
+    authorizationNumber: string;
+    acquirerBIN: string;
+    merchantId: string;
+    transactionStatus: string;
+    responseCodeISO?: string;
+    panTail?: string;
+    panExpiryDate?: string;
+    paymentTypePP?: string;
+    rrn?: string;
+    cardType?: string;
+    cardholderInfo?: string;
+    ibanCode?: string;
+    mac: string;
+}
+export interface PanAliasData {
+    panAlias: string;
+    panAliasRev: string;
+    panAliasExpDate: string;
+    panAliasTail: string;
+    cRecurr?: string;
+    mac: string;
+}
+export interface CreateLinkRequest {
+    /** Send email: Y or N */
+    sendMail: 'Y' | 'N';
+    /** Link expiration (yyyy-MM-ddTHH:mm:ss.SSS) */
+    linkExpirationDate?: string;
+    /** Amount in smallest currency unit (EUR cents) */
+    linkAmount: number;
+    /** ISO currency code (978 = EUR) */
+    linkCurrency?: string;
+    /** Currency exponent */
+    linkExponent?: string;
+    /** Unique order identifier (max 50, must be unique for 5 years) */
+    linkOrderId: string;
+    /** Redirect URL on success (max 254) */
+    linkUrlDone?: string;
+    /** Server-to-server notification URL (max 254) */
+    linkUrlMs: string;
+    /** Accounting mode: D=Deferred, I=Immediate */
+    linkAccountingMode: 'D' | 'I';
+    /** Authorization mode (must be 'I') */
+    linkAuthorMode: 'I';
+    /** Language: ITA or EN */
+    linkLang?: string;
+    /** Shop email for transaction outcome (max 50) */
+    linkShopEmail?: string;
+    /** Additional options (max 10) */
+    linkOptions?: string;
+    /** Commission amount in cents (max 8) */
+    linkCommis?: string;
+    /** Cardholder email (max 50) */
+    linkEmail?: string;
+    /** Cardholder name (max 40) */
+    linkName: string;
+    /** Cardholder surname (max 40) */
+    linkSurname: string;
+    /** Order description (max 140) */
+    linkOrdDescr?: string;
+    /** Operation description (max 100) */
+    linkOpDescr?: string;
+    /** Phone number for Jiffy (10-14 chars) */
+    linkPhoneNumber?: string;
+    /** Min months of card remaining duration (0-60) */
+    linkRemainingDuration?: string;
+    /** Merchant user ID (max 255) */
+    linkUserId?: string;
+    /** Sale identifier (max 15) */
+    linkProductRef?: string;
+    /** Recurring type: R, U, C */
+    linkTRecurr?: 'R' | 'U' | 'C';
+    /** Recurring code (max 50) */
+    linkCRecurr?: string;
+    /** 3DS data (max 5000) */
+    threeDsData?: string;
+    /** Additional options */
+    options?: string;
+}
+export interface LinkCreatedData {
+    completeLink: string;
+    token: string;
+    creationDate: string;
+    status: string;
+    lastUseDate: string;
+    expirationDate: string;
+    revokeDate: string;
+    orderId: string;
+    mac: string;
+}
+export interface ListLinkRequest {
+    /** Search start date (yyyy-MM-dd) */
+    startDate: string;
+    /** Search end date (yyyy-MM-dd) */
+    endDate: string;
+    /** Filter by status */
+    linkStatus?: string;
+    /** Filter by order ID */
+    orderId?: string;
+    /** Filter by token */
+    token?: string;
+    /** Additional options */
+    options?: string;
+}
+export interface RevokeLinkRequest {
+    /** Token of the link to revoke */
+    token: string;
+    /** Additional options */
+    options?: string;
+}
+export interface AccountingRequest {
+    /** Transaction ID from the authorization */
+    transactionId: string;
+    /** Order ID */
+    orderId: string;
+    /** Amount in cents */
+    amount: number;
+    /** ISO currency code */
+    currency?: string;
+    /** Currency exponent */
+    exponent?: string;
+    /** Operation description (max 100) */
+    opDescr?: string;
+    /** Additional options */
+    options?: string;
+}
+export interface ReverseAccountingRequest {
+    /** Transaction ID of the booking to cancel */
+    transactionId: string;
+    /** Order ID */
+    orderId: string;
+    /** Additional options */
+    options?: string;
+}
+export interface RefundRequest {
+    /** Transaction ID of the authorization */
+    transactionId: string;
+    /** Order ID */
+    orderId: string;
+    /** Amount to refund in cents */
+    amount: number;
+    /** ISO currency code */
+    currency?: string;
+    /** Currency exponent */
+    exponent?: string;
+    /** Operation description (max 100) */
+    opDescr?: string;
+    /** Additional options */
+    options?: string;
+}
+export interface OrderStatusRequest {
+    /** Order ID to query */
+    orderId: string;
+    /** Product reference */
+    productRef?: string;
+    /** Additional options */
+    options?: string;
+}
+export interface OperationData {
+    transactionId: string;
+    timestampReq: string;
+    timestampElab: string;
+    srcType: string;
+    amount: string;
+    result: string;
+    status: string;
+    opDescr?: string;
+    mac: string;
+    authorization?: AuthorizationResponse;
+}
+export interface VposResponse {
+    timestamp: string;
+    result: string;
+    mac: string;
+    data?: Record<string, any>;
+}
+export declare const RESULT_CODES: Record<string, string>;
+export declare const LINK_STATUS: Record<string, string>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}