tranzilajs

v1.0.0

Published

6 months ago

A comprehensive TypeScript library for integrating with the Tranzila payment gateway API

0High
0Medium
0Low

nirto111

tranzila payment gateway typescript bit credit-card iframe standing-orders transactions payment-processing

TranzilaJS

npm npm npm

A comprehensive TypeScript library for integrating with the Tranzila payment gateway API. Provides type-safe, well-documented methods for all major Tranzila payment operations.

Features

🚀 Full TypeScript Support - Complete type definitions and IntelliSense
💳 Multiple Payment Methods - Bit payments, credit cards, standing orders, and more
🔐 Automatic Authentication - Built-in header generation and HMAC signing
📱 IFrame Integration - Generate payment links for embedded payments
🔍 Transaction Management - Search, retrieve, and manage transactions
📊 Standing Orders - Create, update, and manage recurring payments
🧪 Comprehensive Testing - Full test suite with mocked responses
📚 Rich Documentation - JSDoc comments and usage examples

🆘 Need Help?

🐛 Found a bug? Open an issue
💡 Have a feature request? Create a feature request
❓ Need support? Open an issue with the "question" label
📚 Official docs? Tranzila API Documentation

Installation

npm install tranzilajs

Getting Started

Prerequisites

Node.js: 18.0.0 or higher
npm: 8.0.0 or higher
Tranzila Account: Merchant account with terminal credentials
Terminal Credentials: Terminal name, public key, and private key

Basic Setup

import { Tranzila } from 'tranzilajs';

// Initialize the client with your credentials
const tranzila = new Tranzila(
  'your-terminal-name',    // From your Tranzila dashboard
  'your-public-key',       // From your Tranzila dashboard
  'your-private-key'       // From your Tranzila dashboard
);

Quick Start Example

// Simple Bit payment initialization
const result = await tranzila.Bit.init({
  terminal_name: 'myterminal',        // Use your actual terminal name
  txn_currency_code: "ILS",
  txn_type: "debit",
  success_url: 'https://your-site.com/success',
  failure_url: 'https://your-site.com/failure',
  notify_url: 'https://your-site.com/notify',
  client: {
    name: 'John Doe',
    email: '[email protected]',
  },
  items: [{
    name: 'Product',
    type: "I",
    unit_price: 100,
    units_number: 1,
    currency_code: "ILS"
  }]
});

if (result.error_code === 0) {
  console.log('Payment URL:', result.sale_url);
  // Redirect user to result.sale_url for payment or render in an iframe
} else {
  console.error('Error:', result.message);
}

JavaScript Usage

const { Tranzila } = require('tranzilajs');

const tranzila = new Tranzila(
  'your-terminal-name',
  'your-public-key',
  'your-private-key'
);

// All methods work the same way
const result = await tranzila.Bit.init({...});

API Reference

Core Classes

`Tranzila`

Main client class for interacting with the Tranzila API.

Constructor:

new Tranzila(terminalName: string, publicKey: string, privateKey: string)

Properties:

Bit - Bit payment operations
IFrame - IFrame payment generation
CreditCard - Credit card operations
StandingOrders - Standing order management
Transactions - Transaction search and retrieval

Bit Payments

`Tranzila.Bit.init(payload: BitInitPayload): Promise<BitInitResponse>`

Initialize a new Bit payment.

Example:

const payload: BitInitPayload = {
  terminal_name: 'your-terminal',
  txn_currency_code: "ILS",
  txn_type: "debit",
  success_url: 'https://your-site.com/success',
  failure_url: 'https://your-site.com/failure',
  notify_url: 'https://your-site.com/notify',
  client: {
    name: 'John Doe',
    email: '[email protected]',
  },
  items: [
    {
      code: "1",
      name: 'Product 1',
      type: "I", // Item
      unit_price: 100,
      units_number: 1,
      vat_percent: 0,
      currency_code: "ILS"
    }
  ]
};

const result = await tranzila.Bit.init(payload);

if (result.error_code === 0) {
  console.log('Bit payment initialized successfully:', result.message);
  console.log('Sale URL:', result.sale_url);
} else {
  console.error('Bit payment initialization failed:', result.message);
}

API Response:

{
  "error_code": 0,
  "message": "Success",
  "sale_url": "https://live.payme.io/sale/generate/..."
}

📖 Full example: usage-examples/bit/init-payment.ts

`Tranzila.Bit.refund(payload: BitRefundPayload): Promise<BitRefundResponse>`

Refund a Bit payment.

Example:

const payload: BitRefundPayload = {
  terminal_name: 'your-terminal',
  transaction_id: 12345,
  amount: 5
};

const result = await tranzila.Bit.refund(payload);

if (result.error_code === 0) {
  console.log('Bit payment refunded successfully:', result.message);
} else {
  console.error('Bit payment refund failed:', result.message);
}

API Response:

{
  "error_code": 0,
  "message": "Success",
  "transaction_result": {
    "processor_response_code": "000",
    "transaction_id": "123456",
    "refund_transaction_id": "123456",
    "amount": "500",
    "refund_amount": 5,
    "refund_type": "complete",
    "currency_code": "ILS",
    "card_locality": "domestic"
  }
}

📖 Full example: usage-examples/bit/refund-payment.ts

Credit Card Operations

`Tranzila.CreditCard.refund(payload: CardRefundPayload): Promise<CardRefundResponse>`

Refund a credit card payment.

Example:

const payload: CardRefundPayload = {
  supplier: "myterminal",
  sum: 5,
  currency: 1,
  TranzilaTK: "1234567890",
  expdate: "0828",
  cred_type: 1, // 1 = Credit card
  TranzilaPW: "1234567890",
  CreditPass: "1234567890",
  tranmode: `C12345`,
  authnr: "00000000",
  contact: "John Doe",
  email: "[email protected]",
  phone: "0000000000"
};

const result = await tranzila.CreditCard.refund(payload);

if (result.includes("Response=000")) {
  console.log('Credit card payment refunded successfully:', result);
} else {
  console.error('Credit card payment refund failed:', result);
}

API Response:

Response=000&TranzilaTK=1234567890&contact=John Doe&phone=0000000000&[email protected]&currency=1&cred_type=1&DclickTK=&supplier=myterminal&authnr=1234567&expdate=0828&tranmode=C123456&sum=1&ConfirmationCode=123456&index=123456&Responsesource=1&Responsecvv=0&Responseid=0&Tempref=123456789&DBFIsForeign=0&DBFcard=2&cardtype=2&DBFcardtype=6&cardissuer=6&DBFsolek=1&cardaquirer=1&tz_parent=myterminal&cred_type_shva=1

📖 Full example: usage-examples/credit-card/refund-payment.ts

IFrame Integration

`Tranzila.IFrame.generateLink(path: string, params: Partial<IFrameParams>): Promise<string>`

Generate a payment link for embedded payment forms.

Example:

const payload: Partial<IFrameParams> = {
  sum: "1",
  cred_type: 1,
  currency: 1,
  tranmode: "AK",
  success_url_address: "https://example.com/success",
  fail_url_address: "https://example.com/fail",
  notify_url_address: "https://example.com/notify",
  email: "[email protected]",
  phone: "0000000000"
};

const result = await tranzila.IFrame.generateLink("iframenew.php", payload);
// Returns: https://direct.tranzila.com/myterminal/iframenew.php?sum=1&cred_type=1&currency=1&tranmode=AK&success_url_address=https%3A%2F%2Fexample.com%2Fsuccess&fail_url_address=https%3A%2F%2Fexample.com%2Ffail&notify_url_address=https%3A%2F%2Fexample.com%2Fnotify&email=john.doe%40example.com&phone=0000000000

📖 Full example: usage-examples/iframe/generate-link.ts

Standing Orders

`Tranzila.StandingOrders.create(payload: CreateStandingOrderPayload): Promise<CreateStandingOrderResponse>`

Create a new standing order for recurring payments.

Example:

const payload: CreateStandingOrderPayload = {
  terminal_name: "myterminal",
  sto_payments_number: 9999,
  charge_frequency: "monthly",
  first_charge_date: "2025-08-14",
  charge_dom: 1,
  vat_percent: 0,
  client: {
    name: "John Doe",
    email: "[email protected]",
    phone_number: "0000000000"
  },
  items: [
    {
      code: "1",
      name: "Test Product",
      units_number: 1,
      unit_price: 5,
      price_currency: "ILS"
    }
  ],
  card: {
    token: "1231234567890",
    expire_month: 8,
    expire_year: 2028
  }
};

const result = await tranzila.StandingOrders.create(payload);

if (result.error_code == 0) {
  console.log('Standing order created successfully:', result.sto_id);
} else {
  console.error('Standing order creation failed:', result.message);
}

API Response:

{
  "error_code": 0,
  "message": "Success",
  "sto_id": "123456"
}

📖 Full example: usage-examples/standing-orders/create-sto.ts

`Tranzila.StandingOrders.retrieve(payload: RetreiveStandingOrdersPayload): Promise<RetreiveStandingOrdersResponse>`

Retrieve standing orders.

Example:

const payload: RetreiveStandingOrdersPayload = {
  terminal_name: "your-terminal-name",
  sto_status: "active"
};

const result = await tranzila.StandingOrders.retrieve(payload);

API Response:

{
  "stos": [
    {
      "sto_id": 123456,
      "terminal_name": "myterminal",
      "sto_payments_number": 9999,
      "charge_frequency": "monthly",
      "first_charge_date": "2025-08-14",
      "charge_dom": 1,
      "last_charge_date": null,
      "next_charge_date": "2025-09-01 00:00:00",
      "create_date": "2025-08-14 14:38:18",
      "sto_first_transaction_id": null,
      "sto_status": "active",
      "charge_amount": "5.0000",
      "card": {
        "token": "123456789",
        "expire_month": 8,
        "expire_year": 28
      },
      "client": {
        "name": "John Doe",
        "email": "[email protected]",
        "phone_number": "0000000000"
      },
      "item": {
        "name": "Test Product",
        "unit_price": 5,
        "units_number": 1
      }
    }
  ]
}

📖 Full example: usage-examples/standing-orders/retrieve-sto.ts

`Tranzila.StandingOrders.update(payload: UpdateStandingOrderPayload): Promise<UpdateStandingOrderResponse>`

Update a standing order.

Example:

const payload: UpdateStandingOrderPayload = {
  terminal_name: "myterminal",
  sto_id: 123456,
  sto_status: "inactive"
};

const result = await tranzila.StandingOrders.update(payload);

API Response:

{
  "error_code": 0,
  "message": "Success"
}

📖 Full example: usage-examples/standing-orders/update-sto.ts

Transaction Management

`Tranzila.Transactions.search(payload: SearchTransactionsPayload): Promise<SearchTransactionsResponse>`

Search and retrieve transactions.

Example:

// Search by date range
const payload: SearchTransactionsPayload = {
  terminal_name: "myterminal",
  transaction_start_date: "2025-01-01",
  transaction_end_date: "2025-01-02"
};

// Search by specific fields
const payload2: SearchTransactionsPayload = {
  terminal_name: "myterminal",
  dfields: [
    {
      name: "transaction_date",
      operator: "equals",
      value: "2025-03-11"
    },
    {
      name: "credit_card_token",
      operator: "equals",
      value: "1234567890"
    }
  ]
};

// Search by transaction index
const payload3: SearchTransactionsPayload = {
  terminal_name: "myterminal",
  transaction_index: 123456
};

const result = await tranzila.Transactions.search(payload);

API Response:

{
  "transactions": [
    {
      "index": "123456",
      "transaction_date": "2025-01-01",
      "transaction_time": "09:23:02",
      "amount": "5500",
      "credit_card_token": "1234",
      "expiration_month": "08",
      "expiration_year": "27",
      "credit_card_owner_id": "1234567890",
      "card_type": "",
      "card_description": "",
      "card_brand": "2",
      "clearing_processor": "",
      "is_foreign": "0",
      "authorization_number": "012345",
      "bank": "",
      "bank_branch": "",
      "bank_account": "",
      "payment_plan": "1",
      "currency": "1",
      "number_of_payments": "0",
      "first_payment_amount": "0",
      "other_payment_amount": "0",
      "host_ip": "127.0.0.1",
      "processor_response_code": "000",
      "tranmode": "A",
      "refnr": "1234567890",
      "tempref": "",
      "cavv": "",
      "eci": "",
      "child_terminal": "myterminal",
      "uid": "",
      "transtatus": "1",
      "telauthability": "1",
      "txnfdid": "12345",
      "cancelfdid": "",
      "txnfdnumber": "123456",
      "cancelfdnumber": "",
      "txn_payment_method": "BIT",
      "txn_type": "DEBIT",
      "pan_entry_mode": "",
      "shopify_id": "",
      "processor": "PAYME",
      "broker": "",
      "broker_product": "",
      "user_defined_1": "",
      "user_defined_2": "",
      "user_defined_3": "",
      "user_defined_4": "",
      "user_defined_5": "",
      "user_defined_6": "",
      "user_defined_7": "",
      "user_defined_8": "",
      "user_defined_9": "",
      "user_defined_10": "",
      "user_defined_11": "",
      "user_defined_12": "",
      "user_defined_13": "",
      "user_defined_14": "",
      "user_defined_15": "",
      "user_defined_16": "",
      "user_defined_17": "",
      "user_defined_18": "",
      "user_defined_19": "",
      "user_defined_20": ""
    }
  ],
  "total": 1,
  "rows": 1
}

📖 Full example: usage-examples/transactions/search-transactions.ts

Callback Handling

When payments are completed, Tranzila sends POST requests to your configured URLs. These webhooks provide real-time updates about payment status and completion.

When Callbacks Are Sent

Bit Payments: After user completes payment on the Bit payment page
Credit Card Payments: After successful/failed credit card processing
Standing Orders: When recurring charges are processed

Callback Types

Notify Callbacks (notify_url): Real-time payment status updates sent to your server
Success Callbacks (success_url): User redirected after successful payment
Failure Callbacks (failure_url): User redirected after failed payment

Implementing Notify Callback

// Example Express.js callback handler
app.post('/notify', (req, res) => {
  const callbackData = req.body;
  
  if (callbackData.Response === '000') {
    // Payment successful
    console.log('Payment completed:', callbackData);
    // Update your database, send confirmation emails, etc.
  } else {
    // Payment failed
    console.log('Payment failed:', callbackData);
    // Handle failure (update your database, notify user, etc.)
  }
  
  res.status(200).send('OK');
});

Example Callback Data

For complete callback examples and webhook data structures, see:

Bit Payment Notify: usage-examples/callbacks/bit-notify-callback.json
Credit Card One Time Notify: usage-examples/callbacks/card-notify-one-time-callback.example.json
Credit Card Recurring Notify: usage-examples/callbacks/card-notify-recurring-callback.example.json
Bit Success: usage-examples/callbacks/bit-success-callback.example.json
Credit Card Success: usage-examples/callbacks/card-success-callback.example.json

Development

Prerequisites

Before developing, ensure you have:

Node.js 18+ and npm 8+ installed
Git for version control
TypeScript knowledge (recommended)

Development Commands

Testing

npm test                    # Run all tests with Jest
npm test -- --watch        # Run tests in watch mode
npm test -- --testPathPattern=bit  # Run specific test files

Code Quality

npm run type-check         # TypeScript compilation check
npm run validate           # Full validation (type-check + test + build)

Building

npm run build             # Build package (CommonJS + ES Modules)
npm run clean             # Clean build artifacts
npm run package           # Create local package for testing

Project Structure

tranzilajs/
├── src/                  # Source code
│   ├── __tests__/        # Test files
│   ├── constants.ts      # API constants
│   ├── index.ts          # Main exports
│   ├── tranzila.ts       # Core Tranzila class
│   └── types.ts          # TypeScript definitions
├── usage-examples/       # Working examples
├── scripts/              # Build and test scripts
└── .github/              # CI/CD workflows

Common Issues & Solutions

TypeScript Errors

Run npm run type-check to identify type issues
Ensure all imports are correct
Check that payload types match expected interfaces

Test Failures

Verify mock responses match actual API responses
Check that test data aligns with usage examples
Run npm test -- --verbose for detailed output

Build Issues

Clean build artifacts: npm run clean
Check Node.js version compatibility
Verify all dependencies are installed: npm ci

Contributing

We welcome contributions!

📖 Contributing Guide: CONTRIBUTING.md - Complete guide for contributors
🐛 Report Issues: GitHub Issues - Bug reports and feature requests
💬 Questions: Open an issue with "question" label for support
🔧 Development: See the Development section above for local setup and testing

Publishing

For information about the automated publishing process and CI/CD pipeline, see PUBLISHING.md.

License

MIT License - see LICENSE for details.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

TranzilaJS

Features

🆘 Need Help?

Installation

Getting Started

Prerequisites

Basic Setup

Quick Start Example

JavaScript Usage

API Reference

Core Classes

Tranzila

Bit Payments

Tranzila.Bit.init(payload: BitInitPayload): Promise<BitInitResponse>

Tranzila.Bit.refund(payload: BitRefundPayload): Promise<BitRefundResponse>

Credit Card Operations

Tranzila.CreditCard.refund(payload: CardRefundPayload): Promise<CardRefundResponse>

IFrame Integration

Tranzila.IFrame.generateLink(path: string, params: Partial<IFrameParams>): Promise<string>

Standing Orders

Tranzila.StandingOrders.create(payload: CreateStandingOrderPayload): Promise<CreateStandingOrderResponse>

Tranzila.StandingOrders.retrieve(payload: RetreiveStandingOrdersPayload): Promise<RetreiveStandingOrdersResponse>

Tranzila.StandingOrders.update(payload: UpdateStandingOrderPayload): Promise<UpdateStandingOrderResponse>

Transaction Management

Tranzila.Transactions.search(payload: SearchTransactionsPayload): Promise<SearchTransactionsResponse>

Callback Handling

When Callbacks Are Sent

Callback Types

Implementing Notify Callback

Example Callback Data

Development

Prerequisites

Development Commands

Testing

Code Quality

Building

Project Structure

Common Issues & Solutions

TypeScript Errors

Test Failures

Build Issues

Contributing

Publishing

License

`Tranzila`

`Tranzila.Bit.init(payload: BitInitPayload): Promise<BitInitResponse>`

`Tranzila.Bit.refund(payload: BitRefundPayload): Promise<BitRefundResponse>`

`Tranzila.CreditCard.refund(payload: CardRefundPayload): Promise<CardRefundResponse>`

`Tranzila.IFrame.generateLink(path: string, params: Partial<IFrameParams>): Promise<string>`

`Tranzila.StandingOrders.create(payload: CreateStandingOrderPayload): Promise<CreateStandingOrderResponse>`

`Tranzila.StandingOrders.retrieve(payload: RetreiveStandingOrdersPayload): Promise<RetreiveStandingOrdersResponse>`

`Tranzila.StandingOrders.update(payload: UpdateStandingOrderPayload): Promise<UpdateStandingOrderResponse>`

`Tranzila.Transactions.search(payload: SearchTransactionsPayload): Promise<SearchTransactionsResponse>`