@deploily/ttk-epay-nodejs-client v1.0.5

TTK-Epay

A comprehensive client SDK for interacting with the TTK-Epay payment processing API. This library provides a simple interface for managing invoices, processing payments, and generating receipts.

Features

• 🧾 Complete invoice management
• 💰 Payment processing functionality
• 📑 PDF receipt generation and email delivery
• 🔍 Payment status verification
• ⚡ Available for both Python and JavaScript environments

Installation

JavaScript (Node.js)

npm install @deploily/ttk-epay-nodejs-client

Quick Start

JavaScript

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client'); 

// Initialize the client
const client = new ttk_epay();

// Example: Get list of invoices
async function getInvoices() {
  try {
    const invoices = await client.get_invoices(1, 10);
    console.log(invoices);
  } catch (error) {
    console.error('Error fetching invoices:', error);
  }
}

getInvoices();

API Reference

Admin Operations

get_invoices(page_number=1, page_size=10)

Retrieves a paginated list of invoices.

Parameters:

• page_number (optional): The page number to retrieve (default: 1)
• page_size (optional): Number of items per page (default: 10)

Returns: A dictionary/object containing:

• List of Invoice objects
• Page information (current page, total pages)

Example (JavaScript):

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client'); 

// Initialize the client
const client = new ttk_epay();

// Example: Get list of invoices
async function listInvoices() {
  try {
    const response = await client.get_invoices(1, 20);
    console.log('Raw response:', JSON.stringify(response, null, 2));
  } catch (error) {
    console.error('Error fetching invoices:', error.message);
  }
}

listInvoices();

create_invoice(invoice_data)

Creates a new invoice.

Parameters:

• invoice_data: An Invoice object containing invoice details

Returns: The created Invoice object with server-assigned fields

Example (JavaScript):

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client'); 
const { Invoice } = require('ttk-epay-nodejs-client/src/models.js'); // Import from your local models file

// Initialize the client
const client = new ttk_epay();

async function createNewInvoice() {
  try {
    // Prepare the invoice data (use plain object)
    const newInvoice = new Invoice ({
      INVOICE_NUMBER: 12345,
      CLIENT_NAME: "Acme Corporation",
      CLIENT_CODE: 789,
      CLIENT_ADDRESS: "123 Business Ave, Suite 100",
      CLIENT_MAIL: "billing@acme.com",
      NET_AMOUNT: 1000.00,
      INVOICE_TVA: 0.19,
      AMOUNT_TVA: 190.00,
      AMOUNT_TTC: 1190.00,
      PRODUCT_NAME: "Enterprise Plan Subscription",
      INVOICE_DATE: "2025-05-08T10:00:00.000Z"
    });

    // Create the invoice
    const createdInvoice = await client.create_invoice(newInvoice);
    console.log(`Created invoice with ID: ${createdInvoice.ID}`);
  } catch (error) {
    console.error('Error creating invoice:', error.message);
  }
}

createNewInvoice();

get_invoice_by_order_id(order_id)

Retrieves a specific invoice by its order ID.

Parameters:

• order_id: The order ID of the invoice to retrieve

Returns: The Invoice object if found

Example (JavaScript):

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client'); 

// Initialize the client
const client = new ttk_epay();

async function findInvoiceByOrderId() {
  try {
    const orderId = "35";
    const invoice = await client.get_invoice_by_order_id(orderId);
    
    console.log(`Found invoice - Order ID: ${invoice.ORDER_ID}, Amount: ${invoice.NET_AMOUNT}, Paid: ${invoice.IS_PAID ? 'Yes' : 'No'}`);
    return invoice;
  } catch (error) {
    console.error(`Error finding invoice: ${error.message}`);
    return null;
  }
}


findInvoiceByOrderId();

update_invoice(invoice_id, invoice_data)

Updates an existing invoice.

Parameters:

• invoice_id: The ID of the invoice to update
• invoice_data: An Invoice object containing updated invoice details

Returns: The updated Invoice object

Example (JavaScript):

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client'); 

// Initialize the client
const client = new ttk_epay();

async function updateExistingInvoice() {
  try {
    const orderId = "35";
    const invoice = await client.get_invoice_by_order_id(orderId);
    
    // Update invoice details
    invoice.NET_AMOUNT = 1500.00;
    invoice.IS_PAID = true; // Change from No to Yes
    
    const result = await client.update_invoice(invoice.ID, invoice);
    console.log(`Updated invoice: Amount=${result.NET_AMOUNT}, Paid=${result.IS_PAID ? 'Yes' : 'No'}`);
    return result;
  } catch (error) {
    console.error(`Update failed: ${error.message}`);
    return null;
  }
}
updateExistingInvoice();

get_payments(options)

Retrieves a list of payments with optional filtering.

Parameters (all optional):

• page_number: Page number for pagination (default: 1)
• page_size: Number of items per page (default: 10)
• satim_order_id: Filter by Satim order ID
• invoice_id: Filter by invoice ID
• from_date: Start date filter (format: 'YYYY-MM-DDTHH:MM:SSZ')
• to_date: End date filter (format: 'YYYY-MM-DDTHH:MM:SSZ')

Returns: A dictionary/object containing payment records and pagination info

Example (JavaScript):

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client'); 

// Initialize the client
const client = new ttk_epay();

async function getRecentPayments() {
  const endDate = new Date().toISOString();
  const startDate = new Date();
  startDate.setDate(startDate.getDate() - 30);
  
  try {
    // Fetching payments from the last 30 days
    const payments = await client.get_payments({
      pageSize: 50,
      from_date: startDate.toISOString(),
      to_date: endDate
    });
    
    // Assuming 'payments' is an array or object with a 'payments' field
    console.log(`Found ${payments.length} payments in the last 30 days`);
  } catch (error) {
    console.error("Error fetching payments:", error);
  }
}


getRecentPayments();

Document Operations

get_pdf_recipt(satim_order_id)

Generates a PDF receipt for a specific payment.

Parameters:

• satim_order_id: The Satim order ID for the payment

Returns: PDF receipt as binary data

Example (JavaScript):

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client'); 

// Initialize the client
const client = new ttk_epay();

const fs = require('fs');

async function savePdfReceipt() {
  const satimOrderId = "SATIM-12345";
  
  try {
    // Fetching the PDF receipt data
    const pdfData = await client.get_pdf_recipt(satimOrderId);
    
    // Writing the PDF data to a file
    fs.writeFileSync(`receipt_${satimOrderId}.pdf`, pdfData);
    console.log(`Receipt saved to receipt_${satimOrderId}.pdf`);
  } catch (error) {
    console.error("Error saving PDF receipt:", error);
  }
}



savePdfReceipt();

send_pdf_recipt_mail(satim_order_id, email)

Sends a PDF receipt to a specified email address.

Parameters:

• satim_order_id: The Satim order ID for the payment
• email: The email address to send the receipt to

Returns: API response indicating success or failure

Example (JavaScript):

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client'); 

// Initialize the client
const client = new ttk_epay();

async function emailReceipt() {
  const satimOrderId = "SATIM-12345";
  const email = "customer@example.com";
  
  try {
    // Sending the receipt via email
    const result = await client.send_pdf_recipt_mail(satimOrderId, email);
    
    // Check if the result is in the expected format or status
    if (result) {
      console.log(`Receipt sent successfully to ${email}`);
    } else {
      console.log("Receipt could not be sent. No result returned.");
    }
  } catch (error) {
    console.error(`Failed to send receipt: ${error.message}`);
  }
}


emailReceipt();

Payment Operations

post_payement(payment_data)

Processes a new payment.

Parameters:

• payment_data: An InvoiceDto object containing payment details

Returns: Payment processing result object

Example (JavaScript):

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client');
const { InvoiceDto } = require('ttk-epay-nodejs-client/src/models.js'); // Import from your local models file

// Initialize the client
const client = new ttk_epay();

async function processPayment() {
  // Create payment data with a unique invoice number (using timestamp)
  const uniqueInvoiceNumber = Math.floor(Date.now() / 1000); // Unix timestamp
  const payment = new InvoiceDto({
    INVOICE_NUMBER: uniqueInvoiceNumber,
    ORDER_ID: `ORD-${uniqueInvoiceNumber}`,
    CLIENT_NAME: "Jane Smith",
    CLIENT_CODE: 456,
    CLIENT_ADDRESS: "456 Customer St.",
    CLIENT_MAIL: "jane@example.com",
    PRODUCT_NAME: "Premium Package",
    NET_AMOUNT: 750.00
  });

  try {
    // Process the payment
    const result = await client.post_payement(payment);
    
    // Debug the result
    console.log("Full API response:", JSON.stringify(result, null, 2));
    
    // Check if the result has the expected fields
    if (result && result.ERROR_CODE === "0") {
      if (result.ORDER_ID && result.FORM_URL) {
        console.log(`Payment initialized successfully!`);
        console.log(`Order ID: ${result.ORDER_ID}`);
        console.log(`Payment Form URL: ${result.FORM_URL}`);
      } else {
        console.error("Success response missing ORDER_ID or FORM_URL:", result);
      }
    } else if (result && result.ERROR_CODE) {
      console.error(`Payment API Error (${result.ERROR_CODE}): ${result.ERROR_MESSAGE}`);
    } else {
      console.error("Unexpected result format:", result);
    }
  } catch (error) {
    console.error(`Error processing payment: ${error.message}`);
  }
}

processPayment();

get_payment_status(satim_order_id)

Checks the status of a payment.

Parameters:

• satim_order_id: The Satim order ID for the payment

Returns: Payment status object with transaction details

Example (JavaScript):

const { ttk_epay } = require('@deploily/ttk-epay-nodejs-client');
const client = new ttk_epay();

async function checkPaymentStatus() {
  try {
    const status = await client.get_payment_status("8LmjDNjisi0A5EAAGBYM");
    
    if (!status) {
      return { error: "No payment status received" };
    }

    // Determine payment status text
    let statusText;
    if (status.ORDER_STATUS === 0) statusText = "Rejected";
    else if (status.ORDER_STATUS === 1) statusText = "Processing";
    else if (status.ORDER_STATUS === 2) statusText = "Completed";
    else statusText = "Unknown";

    return {
      status: statusText,
      amount: status.AMOUNT,
      currency: status.CURRENCY,
      error: status.ERROR_CODE !== "0" ? status.ERROR_MESSAGE : null
    };

  } catch (error) {
    return { error: "Failed to check payment status" };
  }
}

// Usage
checkPaymentStatus().then(result => {
  console.log(result);
});

Data Models

Invoice

The primary data model for invoice operations.

Fields

InvoiceDto

Simplified data model for payment processing operations.

Fields

Error Handling

JavaScript implementations handle errors differently:

JavaScript

The JavaScript library uses Promise-based error handling:

const axios = require('axios');

// Sample client function simulating the API call
const client = {
  get_invoice_by_order_id: (orderId) => {
    return new Promise((resolve, reject) => {
      // Simulating a response or error based on the orderId
      if (orderId === "NON-EXISTENT") {
        reject(new Error("Invoice not found"));
      } else {
        resolve({ orderId: orderId, amount: 100 });
      }
    });
  }
};

// 1. Promise-based error handling using .then() and .catch()
client.get_invoice_by_order_id("NON-EXISTENT")
  .then(invoice => {
    console.log("Invoice found:", invoice);
  })
  .catch(error => {
    console.error("Error details:", error.message);
  });

// 2. Async/await error handling with try-catch
async function fetchInvoice() {
  try {
    const invoice = await client.get_invoice_by_order_id("NON-EXISTENT");
    console.log("Invoice found:", invoice);
  } catch (error) {
    console.error("Error details:", error.message);
  }
}

fetchInvoice();

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.