TestLuy Payment SDK


🚀 Overview

The TestLuy Payment SDK provides a robust, production-ready JavaScript interface for integrating applications with the TestLuy Payment Simulator platform. Designed for both development and deployment environments, it seamlessly handles Cloudflare Tunnel Zero Trust protection, rate limiting, and complex authentication scenarios.

✅ Successfully tested in production environments including Vercel, Render, Netlify, and other deployment platforms.

$3

- 🛡️ Cloudflare Tunnel Zero Trust Support: Automatic bypass for deployment environments
- 🔐 HMAC-SHA256 Authentication: Secure request signing with automatic credential validation
- ⚡ Smart Environment Detection: Automatically adapts behavior for local vs deployment environments
- 🔄 Intelligent Retry Logic: Exponential backoff with jitter for resilient API calls
- 📊 Advanced Rate Limiting: Subscription-aware rate limiting with graceful degradation
- 🖥️ Multi-Platform Compatibility: Works in Node.js, Next.js, Express, and modern build tools
- 📈 Comprehensive Logging: Configurable logging with sensitive data masking
- 🧪 Extensive Testing: 100% test coverage with integration and unit tests
- 📚 Type Safety: Full TypeScript definitions included

📦 Installation

``bash

Using npm

npm install testluy-payment-sdk@latest

Using yarn

yarn add testluy-payment-sdk@latest

Using pnpm

pnpm add testluy-payment-sdk
`

🚨 Security Notice

⚠️ CRITICAL: Server-Side Only Usage

Your secretKey is highly sensitive. Never expose it in client-side code. Always use this SDK on your server-side:

- ✅ Node.js backends
- ✅ Next.js API routes
- ✅ Express route handlers
- ✅ Serverless functions
- ❌ Frontend JavaScript (React, Vue, etc.)

🛠️ Quick Start

$3

`javascript
import TestluyPaymentSDK from 'testluy-payment-sdk';

// Initialize the SDK
const sdk = new TestluyPaymentSDK({
clientId: process.env.TESTLUY_CLIENT_ID,
secretKey: process.env.TESTLUY_SECRET_KEY,
baseUrl: process.env.TESTLUY_BASE_URL || 'https://api-testluy.paragoniu.app'
});

// Validate credentials (recommended)
await sdk.init();

// Initiate a payment
const { paymentUrl, transactionId } = await sdk.initiatePayment(
25.50,
'https://yourapp.com/payment-callback',
'https://yourapp.com/cancel'
);

// Redirect user to payment URL
console.log('Payment URL:', paymentUrl);
console.log('Transaction ID:', transactionId);
`

$3

Create a .env file in your project root:

`env

TestLuy SDK Configuration

TESTLUY_CLIENT_ID=your_client_id_here
TESTLUY_SECRET_KEY=your_secret_key_here
TESTLUY_BASE_URL=https://api-testluy.paragoniu.app

Optional: Override for different environments

TESTLUY_BASE_URL=http://localhost:8000 # Local development

`

⚙️ Advanced Configuration

$3

`javascript
const sdk = new TestluyPaymentSDK({
// Required
clientId: 'your-client-id',
secretKey: 'your-secret-key',
baseUrl: 'https://api-testluy.paragoniu.app',

// Optional: Smart routing (auto-enabled)
enableSmartRouting: true,
bypassUrl: 'https://alt-endpoint.example.com', // Custom bypass endpoint

// Optional: Retry configuration
retryConfig: {
maxRetries: 3,
baseDelay: 1000, // 1 second initial delay
maxDelay: 30000, // 30 seconds max delay
backoffFactor: 2, // Exponential backoff
jitterFactor: 0.1 // Add random jitter
},

// Optional: Cloudflare bypass settings
cloudflareConfig: {
enabled: true, // Auto-enabled for deployment environments
rotateUserAgent: true,
addBrowserHeaders: true
},

// Optional: Logging configuration
loggingConfig: {
level: 'info', // 'debug', 'info', 'warn', 'error', 'silent'
includeHeaders: false, // Include HTTP headers in logs
includeBody: false, // Include request/response bodies
maskSensitive: true, // Mask sensitive data (recommended)
format: 'text', // 'text' or 'json'
colorize: true // Colorize console output
}
});
`

$3

The SDK automatically detects your deployment environment and adjusts behavior accordingly:

`javascript
// Development Environment (Local)
const sdk = new TestluyPaymentSDK({
clientId: process.env.TESTLUY_CLIENT_ID,
secretKey: process.env.TESTLUY_SECRET_KEY,
baseUrl: 'http://localhost:8000', // Local backend
loggingConfig: { level: 'debug' } // Verbose logging for development
});

// Production Environment (Auto-detected)
const sdk = new TestluyPaymentSDK({
clientId: process.env.TESTLUY_CLIENT_ID,
secretKey: process.env.TESTLUY_SECRET_KEY,
baseUrl: 'https://api-testluy.paragoniu.app',
loggingConfig: { level: 'warn' } // Minimal logging for production
});
// Cloudflare bypass headers automatically applied in deployment environments
`

📖 API Reference

$3

#### new TestluyPaymentSDK(options)

Creates a new SDK instance with the specified configuration.

Parameters:
- options.clientId (string, required): Your TestLuy application client ID
- options.secretKey (string, required): Your TestLuy application secret key
- options.baseUrl (string, optional): API base URL (defaults to production endpoint)
- Additional options as shown in Advanced Configuration

Throws: Error if required parameters are missing or invalid

$3

#### async init()

Validates credentials and initializes the SDK. Recommended to call before other operations.

Returns: Promise - true if credentials are valid

Example:
`javascript
try {
await sdk.init();
console.log('SDK initialized successfully');
} catch (error) {
console.error('Invalid credentials:', error.message);
}
`

#### async initiatePayment(amount, callbackUrl, backUrl?)

Initiates a payment process and returns a payment URL.

Parameters:
- amount (number, required): Payment amount (must be positive)
- callbackUrl (string, required): URL for payment completion callback
- backUrl (string, optional): URL for user cancellation/back navigation

Returns: Promise<{paymentUrl: string, transactionId: string}>

Example:
`javascript
const result = await sdk.initiatePayment(
10.50,
'https://yourapp.com/payment-success',
'https://yourapp.com/payment-cancel'
);

console.log('Payment URL:', result.paymentUrl);
console.log('Transaction ID:', result.transactionId);
`

#### async getPaymentStatus(transactionId)

Retrieves the current status of a payment transaction.

Parameters:
- transactionId (string, required): Transaction ID from initiatePayment

Returns: Promise