sofizpay-sdk-js

v1.2.1

Published

2 months ago

A comprehensive JavaScript SDK for secure digital payments and transactions

0High
0Medium
0Low

kenandarabah

payment digital-payments transaction sdk sofizpay finance web3 javascript typescript nodejs browser react vue

SofizPay SDK JS

The official JavaScript SDK for secure digital payments and transactions.

Quick Start

Installation

npm install sofizpay-sdk-js

Basic Usage

import SofizPaySDK from 'sofizpay-sdk-js';

const sdk = new SofizPaySDK();

// Send payment
const result = await sdk.submit({
  secretkey: 'YOUR_SECRET_KEY',
  destinationPublicKey: 'RECIPIENT_PUBLIC_KEY',
  amount: 100,
  memo: 'Payment description'
});

console.log(result.success ? 'Payment sent!' : result.error);

Features

✅ Send Secure Payments - Instant digital transactions
✅ Get Account Balance - Real-time balance checking
✅ Transaction History - Complete transaction records
✅ Search & Filter - Find transactions by memo or hash
✅ Real-time Streaming - Live transaction notifications with flexible options
✅ Multi-platform - Works everywhere (Browser, Node.js, React, Vue)
✅ Flexible Monitoring - Stream from now or with full history, customizable intervals

Usage Examples

Browser (CDN)

<script src="https://unpkg.com/[email protected]/dist/stellar-sdk.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/forge.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/axios.min.js"></script>
<script src="https://unpkg.com/sofizpay-sdk-js@latest/dist/sofizpay-sdk.umd.js"></script>

<script>
const sdk = new SofizPaySDK();

async function sendPayment() {
  const result = await sdk.submit({
    secretkey: 'YOUR_SECRET_KEY',
    destinationPublicKey: 'DESTINATION_KEY',
    amount: 50,
    memo: 'Web payment'
  });
  
  alert(result.success ? 'Success!' : result.error);
}
</script>

React

import { useState, useEffect } from 'react';
import SofizPaySDK from 'sofizpay-sdk-js';

function WalletComponent() {
  const [sdk] = useState(() => new SofizPaySDK());
  const [balance, setBalance] = useState(0);

  useEffect(() => {
    const loadBalance = async () => {
      const result = await sdk.getBalance('YOUR_PUBLIC_KEY');
      if (result.success) setBalance(result.balance);
    };
    loadBalance();
  }, []);

  const sendPayment = async () => {
    const result = await sdk.submit({
      secretkey: 'YOUR_SECRET_KEY',
      destinationPublicKey: 'RECIPIENT_KEY',
      amount: 25,
      memo: 'React payment'
    });
    
    if (result.success) {
      alert('Payment sent successfully!');
      // Reload balance
    }
  };

  return (
    <div>
      <h2>Balance: {balance}</h2>
      <button onClick={sendPayment}>Send Payment</button>
    </div>
  );
}

Node.js

import SofizPaySDK from 'sofizpay-sdk-js';

const sdk = new SofizPaySDK();

async function main() {
  // Check balance
  const balance = await sdk.getBalance('YOUR_PUBLIC_KEY');
  console.log(`Current balance: ${balance.balance}`);

  // Send payment
  const payment = await sdk.submit({
    secretkey: 'YOUR_SECRET_KEY',
    destinationPublicKey: 'RECIPIENT_KEY',
    amount: 100,
    memo: 'Server payment'
  });

  console.log(payment.success ? 'Payment sent!' : payment.error);
}

main();

API Reference

Core Methods

| Method | Description | Example | |--------|-------------|---------| | submit(data) | Send secure payment | sdk.submit({secretkey, destinationPublicKey, amount, memo}) | | getBalance(publicKey) | Get account balance | sdk.getBalance('GXXX...') | | getTransactions(publicKey, limit) | Get transaction history | sdk.getTransactions('GXXX...', 50) | | getTransactionByHash(hash) | Find transaction by hash | sdk.getTransactionByHash('abc123...') | | searchTransactionsByMemo(publicKey, memo, limit) | Search by memo | sdk.searchTransactionsByMemo('GXXX...', 'payment', 50) | | getPublicKey(secretKey) | Get public key from secret key | sdk.getPublicKey('SXXX...') | | startTransactionStream(publicKey, callback, fromNow, checkInterval) | Start real-time monitoring | sdk.startTransactionStream('GXXX...', callback, true, 30) | | stopTransactionStream(publicKey) | Stop real-time monitoring | sdk.stopTransactionStream('GXXX...') | | getStreamStatus(publicKey) | Check stream status | sdk.getStreamStatus('GXXX...') | | makeCIBTransaction(transactionData) | Create bank transaction | sdk.makeCIBTransaction({account, amount, full_name, phone, email}) | | verifySignature(verificationData) | Verify digital signature | sdk.verifySignature({message, signature_url_safe}) |

Bank Transaction Parameters

const transactionData = {
  account: 'string',          // User account identifier
  amount: 'number',           // Transaction amount (must be > 0)
  full_name: 'string',        // Customer full name
  phone: 'string',            // Customer phone number
  email: 'string',            // Customer email address
  
  // Optional parameters
  memo: 'string',             // Transaction description/memo
  return_url: 'string',       // URL to redirect after payment
  redirect: 'boolean'         // Whether to redirect automatically
};

Signature Verification Parameters

const verificationData = {
  message: 'string',              // Original message to verify
  signature_url_safe: 'string'   // Base64URL-encoded signature
};

Advanced Features

// Get public key from secret key
const result = await sdk.getPublicKey('YOUR_SECRET_KEY');
if (result.success) {
  console.log('Public key:', result.publicKey);
}

// Real-time transaction monitoring - New transactions only
await sdk.startTransactionStream('YOUR_PUBLIC_KEY', (newTx) => {
  console.log('New transaction received:', newTx);
}, true, 30); // fromNow=true, checkInterval=30 seconds

// Real-time monitoring with full history first
await sdk.startTransactionStream('YOUR_PUBLIC_KEY', (transaction) => {
  if (transaction.isHistorical) {
    console.log('Historical transaction:', transaction);
  } else {
    console.log('New transaction received:', transaction);
  }
}, false, 15); // fromNow=false, checkInterval=15 seconds

// Stop monitoring
await sdk.stopTransactionStream('YOUR_PUBLIC_KEY');

// Check stream status
const status = await sdk.getStreamStatus('YOUR_PUBLIC_KEY');
console.log('Stream active:', status.isActive);

// Search transactions by memo with custom limit
const searchResults = await sdk.searchTransactionsByMemo('YOUR_PUBLIC_KEY', 'payment', 100);
if (searchResults.success) {
  console.log('Found transactions:', searchResults.transactions);
}

// Get specific transaction by hash
const transaction = await sdk.getTransactionByHash('TRANSACTION_HASH_HERE');
if (transaction.success) {
  console.log('Transaction details:', transaction.transaction);
}

Utility Functions

// Convert secret key to public key
const keyResult = await sdk.getPublicKey('SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
if (keyResult.success) {
  console.log('Derived public key:', keyResult.publicKey);
  // Use this public key for balance checking, transaction queries, etc.
  const balance = await sdk.getBalance(keyResult.publicKey);
}

// Get complete transaction history with custom limit
const allTransactions = await sdk.getTransactions('YOUR_PUBLIC_KEY', 200);
if (allTransactions.success) {
  console.log(`Found ${allTransactions.transactions.length} transactions`);
  allTransactions.transactions.forEach(tx => {
    console.log(`${tx.type}: ${tx.amount} - ${tx.memo} (${tx.timestamp})`);
  });
}

// Search for specific payments by memo
const orderPayments = await sdk.searchTransactionsByMemo('YOUR_PUBLIC_KEY', 'Order #12345', 10);
if (orderPayments.success && orderPayments.transactions.length > 0) {
  console.log('Found order payments:', orderPayments.transactions);
} else {
  console.log('No payments found for this order');
}

Bank Integration

// Create bank transaction
const bankResult = await sdk.makeCIBTransaction({
  account: 'YOUR_PUBLIC_KEY',
  amount: 150,
  full_name: 'YOUR_NAME',
  phone: '+213*********',
  email: 'YOUR_EMAIL',
  memo: 'Payment',
  return_url: 'https://yoursite.com/payment-success',
  redirect: 'yes' // or 'no'
});

if (bankResult.success) {
  console.log('Bank transaction created:', bankResult.url);
  // Redirect user to payment page or handle response
} else {
  console.error('Bank transaction failed:', bankResult.error);
}

Real-time Streaming Options

The startTransactionStream method accepts these parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | publicKey | string | - | Required. Account public key to monitor | | callback | function | - | Required. Function called for each transaction | | fromNow | boolean | true | true: Only new transactions, false: Load history then monitor | | checkInterval | number | 30 | Reconnection interval in seconds (5-300) |

// Example: Load last 200 transactions then monitor new ones
await sdk.startTransactionStream(
  'GXXX...', 
  (tx) => console.log(tx), 
  false,  // Load historical transactions first
  10      // Check every 10 seconds
);

// Example: Monitor only new transactions with custom interval
await sdk.startTransactionStream(
  'GXXX...', 
  (tx) => console.log('Live transaction:', tx), 
  true,   // From now only
  60      // Check every minute
);

Digital Signature Verification

// Verify digital signature (for webhook validation)
const isValid = sdk.verifySignature({
  message: 'wc_order_LI3SLQ7xA7IY9cib84907success23400',
  signature_url_safe: 'jHrONYl2NuBhjAYTgRq3xwRuW2ZYZIQlx1VWgiObu5FrSnY78pQ...'
});

if (isValid) {
  console.log('Signature is valid - proceed with order');
} else {
  console.log('Invalid signature - reject request');
}

// Common use case: Webhook validation
app.post('/webhook', (req, res) => {
  const { message, signature } = req.body;
  
  if (sdk.verifySignature({ message, signature_url_safe: signature })) {
    // Process the webhook
    res.status(200).send('OK');
  } else {
    res.status(400).send('Invalid signature');
  }
});

Response Format

All methods return a consistent response format:

// Success
{
  success: true,
  // ... method-specific data
  timestamp: "2025-07-28T10:30:00.000Z"
}

// Error
{
  success: false,
  error: "Error description",
  timestamp: "2025-07-28T10:30:00.000Z"
}

Configuration

The SDK is pre-configured for secure digital transactions:

Network: Mainnet
Security: Enterprise-grade encryption
Performance: Optimized for high-throughput operations

Security Best Practices

⚠️ Important Security Notes:

Never expose secret keys in client-side code
Use environment variables for sensitive data
Always test on test environment first
Validate all inputs before sending transactions

// ✅ Good - Environment variable
const secretKey = process.env.SECRET_KEY;

// ❌ Bad - Hardcoded in code
const secretKey = 'SXXXXXXXXXXXXX...';

Transaction Flow

graph TD
    A[Initialize SDK] --> B[Authenticate]
    B --> C{Transaction Type}
    C -->|Payment| D[Submit Payment]
    C -->|Query| E[Get Balance/History]
    C -->|Stream| F[Monitor Real-time]
    D --> G[Payment Processing]
    E --> H[Return Data]
    F --> I[Live Updates]
    G --> J[Success/Error Response]

Examples Repository

Find complete examples at: github.com/kenandarabeh/sofizpay-sdk/examples

Support

📚 Documentation: Full API Docs
🐛 Issues: Report Bug
💬 Discussions: Community Help
🌐 Website: SofizPay.com

Use Cases

E-commerce Integration

Perfect for online stores needing secure payment processing:

// Process customer payment
const orderPayment = await sdk.submit({
  secretkey: process.env.STORE_SECRET_KEY,
  destinationPublicKey: customerKey,
  amount: orderTotal,
  memo: `Order #${orderId}`
});

Financial Applications

Built for fintech apps requiring real-time transaction monitoring:

// Monitor account activity
await sdk.startTransactionStream(userKey, (transaction) => {
  updateUI(transaction);
  notifyUser(transaction);
});

Enterprise Solutions

Scalable for high-volume business operations:

// Batch processing
const results = await Promise.all(
  payments.map(payment => sdk.submit(payment))
);

Performance

Speed: Sub-second transaction processing
Reliability: 99.9% uptime guarantee
Scalability: Handles thousands of transactions per second
Global: Worldwide transaction support

License

Built with ❤️ for Sofizpay | Version 1.2.1