📘 TTK ePay Module

TTK ePay is a powerful and flexible electronic payment module developed as part of the Deploily web application. Designed to streamline the online payment experience, it empowers users to send payment links directly to their clients and provides a secure, user-friendly interface for completing transactions.

Built on an MVC architecture, TTK ePay enables users to manage and track client payments efficiently through its intuitive Admin Console. Users can create, update, and monitor invoices via a centralized dashboard, ensuring complete control over payment operations.

TTK ePay also includes a robust RESTful API, allowing developers to integrate the module into their own applications and customize the payment experience to fit their specific business needs.

Payments through TTK ePay are securely processed via Edahabia and bank cards, providing flexibility and trust for both users and clients.

🧭 TTK ePay – Full Workflow

📈 BPMN Diagram

1️⃣ Order TTK ePay in Deploily

• Log into your Deploily account
• Go to Applications > TTK ePay
• Purchase the module
• You will get:
  • - API Base URL
  • - Secret Key

2️⃣ Register on cibweb.dz

• Visit cibweb.dz
• Submit your company documents
• Obtain the necessary credentials (e.g. Merchant ID, Terminal ID)

3️⃣ Configure "TTK ePay" in Deploily

• Navigate to My Applications > TTK ePay > Settings
• Fill parameters
• Click Save

4️⃣ Use the Admin Console to Create Invoices

• Go to TTK ePay > Invoices
• Click Create Invoice
• Click Generate Link and share it with your client

5️⃣ Test with the MVC (Web) Interface

• Your client opens the secure payment page
• Enters invoice number and client code and pay

♻️ Ideal for testing before API integration

6️⃣ Use the APIs (Node.js / Python)

7️⃣ Monitor Results in the Admin Console (InvoicesPaymnts)

---

🧩 TTK ePay MVC

The MVC integration enables your users to make payments for their invoices directly through your web application's interface. This approach offers flexibility and a streamlined payment experience.

💳 How It Works

• The user accesses a payment page and provides their invoice number and client code.
• The system fetches and verifies the invoice details from your backend (or through the TTK ePay SDK).
• If the user chooses to proceed with payment via our module, a confirmation screen is displayed.
• Upon confirmation, the user is redirected to the SATIM secure payment interface.
• The user enters their bank card credentials and completes the transaction securely.
• After payment, the user is redirected back to your application with the result.

🔐 Security Notes

• Payment is handled securely through SATIM's official gateway.
• No card credentials are ever stored or transmitted by your system.
• You must validate the payment result through TTK ePay's backend confirmation route.

📦 Example Flow

1. User navigates to /payement-url
2. Enters invoice number and client code
3. Clicks "Pay"
4. Sees a confirmation modal
5. Redirects to SATIM
6. Completes payment
7. Gets redirected back with status: success or failure

---

🌐 TTK ePay API

TTK ePay offers official SDKs for Node.js and Pythonto help developers easily integrate e-payment capabilities into their applications. Below is an overview of the available packages and usage examples.

📦 Node.js Client

Official npm package: @deploily/ttk-epay-nodejs-client

Installation

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

Example Usage

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

            const client = new ttk_epay({
              baseUrl: 'https://your-app.com',
              secretKey: 'your-secret-key'
            });

            // List invoices
            const invoices = await client.get_invoices(1, 10);
            

Available Methods

• getInvoices(page, size) – Paginated invoice listing
• createInvoice(data) – Create a new invoice
• getInvoiceById(invoiceId) – Fetch invoice via ID
• updateInvoice(invoiceId, data) – Update an invoice
• getPayments(options) – Filter and list payments
• getPaymentById(paymentId) – Fetch payment via ID
• postPayement(data) – Register a new payment
• getPdfRecipt(orderId) – Get a PDF receipt
• sendPdfReceiptMail(orderId, email) – Send receipt by email

🐍 Python Client

Official PyPi package: ttk-epay – GitHub source: ttk-epay-python-client

Installation

pip install ttk-epay

Example Usage

from ttk_epay.client import TtkEpay

client = TtkEpay(
    base_url="https://your-app.com",
    secret_key="your-secret-key"
)

# List invoices
invoices = client.get_invoices(page=1, size=10)

Available Methods

• get_invoices(page, size)
• create_invoice(data)
• get_invoice_by_order_id(order_id)
• update_invoice(invoice_id, data)
• get_payments(params)
• post_payement(data)
• get_pdf_recipt(order_id)
• send_pdf_recipt_mail(order_id, email)

---

🖥️ TTK ePay Admin Console

The TTK ePay Admin Console is a secure and intuitive web dashboard that allows users to manage their payment operations, invoices, and receipts efficiently. Once you have purchased the module, you can access this interface to fully configure and monitor your e-payment system.

🔐 Registration

After purchasing the module, you'll receive a Base URL and a Secret Key. Use these credentials to register your service in the admin console.

• Access the registration form
• Enter your application URL
• Paste your secret key
• Submit to activate your integration

📄 Invoice Management

From the dashboard, users can view all invoices in a searchable, paginated table. You can:

• View all invoices
• Create new invoices
• Update existing invoices

💳 Payments Overview

The payments section provides a comprehensive view of all received payments. You can:

• Browse and filter all payment records
• View payment details including amount, date, status, and invoice linkage
• Download the full list of payments (CSV or Excel)
• Download individual receipts as PDFs

📥 Downloadable Documents

• Download receipts as PDFs
• Export full payment history as CSV

💳 TTK ePay Satim Emulator

📘 SATIM Emulator

The SATIM Emulator is a secure sandbox environment provided for developers and QA engineers to test online payment flows. It reproduces the behavior of the official SATIM gateway, but without involving any real transactions. This makes it safe and efficient for integration, testing, and troubleshooting.

Screenshot of the SATIM Emulator interface for testing payments.

🔄 Payment Workflow

1. Register: Create an order via /register.do
2. Redirect: User is redirected to the provided formUrl
3. Confirm: Validate the order using /confirmOrder.do
4. Result: Application handles returnUrl or failUrl

🔎 Why use the Emulator?

• Validate payment flows without using real money
• Obtain safe satim_username and satim_password for tests
• Simulate success and failure scenarios
• Verify your integration before going live

⚙️ How to Connect

• Login to your Admin Console
• Navigate to My Profile
• Copy the generated satim_username and satim_password
• Use them inside your development/test environment

🚀 Usage in Tests

• Register a new test payment request
• Confirm the payment to simulate approval
• Trigger failUrl to simulate rejection

📡 Example cURL — Register

curl -X GET "http://127.0.0.1:8000/api/payment/rest/register.do?orderNumber=123&amount=100&currency=012&returnUrl=http://localhost/success&failUrl=http://localhost/fail&language=EN&userName=satim_demo&password=demoPass&description=TestPayment&jsonParams=%7B%7D" \
-H "Accept: application/json"

Example response:

{
  "orderId": 11,
  "formUrl": "http://127.0.0.1:8000/paymentWebpage?orderId=11",
  "errorMessage": "",
  "errorCode": ""
}

📡 Example cURL — Confirm

curl -X GET "http://127.0.0.1:8000/api/payment/rest/confirmOrder.do?language=EN&orderId=8&userName=satim_demo&password=demoPass" \
-H "Accept: application/json"

Example response:

{
  "orderStatus": 2,
  "errorCode": 0,
  "errorMessage": "",
  "actionCode": 0,
  "actionCodeDescription": "Payment already confirmed",
  "amount": 100,
  "currency": 10
}

✅ Best Practices

• Always test with multiple scenarios: success, failure, timeout
• Log all requests and responses during development
• Keep emulator and production credentials separate
• Automate regression tests using the emulator

❓ FAQ

• Q: My payments always fail.
  A: Check if you’re using emulator credentials, not production ones.
• Q: Redirect doesn’t work.
  A: Ensure your returnUrl and failUrl are accessible from your local/test environment.
• Q: Can I use Postman?
  A: Yes, you can run all endpoints from Postman or cURL.

⚠️ Notes

• No real banking transactions occur in the emulator
• Use only for development and QA phases
• Replace emulator credentials with real SATIM details before production