sagapay-sdk v4.3.0

SagaPay SDK

SagaPay: Blockchain Payment Processing Simplified

SagaPay (https://sagapay.net) is the world's first free, non-custodial blockchain payment gateway service provider, enabling businesses to seamlessly integrate cryptocurrency payments without holding customer funds. With enterprise-grade security and zero transaction fees, SagaPay empowers merchants to accept crypto payments across multiple blockchains while maintaining full control of their digital assets.

Installation

npm install sagapay-sdk

Initialization

import { SagaPayClient } from 'sagapay-sdk';

const client = new SagaPayClient('your-api-key', 'your-api-secret');

Features

• Deposit address generation
• Withdrawal processing
• Transaction status checking
• Wallet balance fetching
• Multi-chain support (ERC20, BEP20, TRC20, POLYGON, SOLANA)
• Webhook notifications (IPN)
• Custom UDF field support
• Rate limiting protection
• Zero transaction fees
• Non-custodial architecture
• Enterprise-grade security

API Reference

Create Deposit

await client.createDeposit({
    networkType: 'BEP20',
    contractAddress: '0',    // Use '0' for mainnet tokens
    amount: '1.5',
    ipnUrl: 'https://callback.com/ipn',
    udf: 'order-123',       // Optional
    type: 'TEMPORARY'       // Optional: TEMPORARY or PERMANENT
});

Response:

{
    "id": "deposit-id",
    "address": "crypto-address",
    "expiresAt": "2024-01-09T12:00:00Z",
    "amount": "1.5",
    "status": "PENDING"
}

Create Withdrawal

await client.createWithdrawal({
    networkType: 'ERC20',
    contractAddress: '0',    // Use '0' for mainnet tokens
    address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    amount: '0.5',
    ipnUrl: 'https://callback.com/ipn',
    udf: 'withdrawal-123'    // Optional
});

Response:

{
    "id": "withdrawal-id",
    "status": "PENDING",
    "fee": "0.001"
}

Check Transaction Status

await client.checkTransactionStatus('0x123abc...', 'deposit');

Response:

{
  "address": "0x123abc...",
  "transactionType": "deposit",
  "count": 2,
  "transactions": [
    {
      "id": "tx-uuid-1",
      "transactionType": "deposit",
      "status": "COMPLETED",
      "amount": "10.5",
      "createdAt": "2025-03-16T12:00:00Z",
      "updatedAt": "2025-03-16T12:15:00Z",
      "txHash": "0xf7e...",
      "networkType": "ERC20",
      "contractAddress": "0x...",
      "address": "0x123abc...",
      "token": {
        "networkType": "ERC20",
        "contractAddress": "0x...",
        "symbol": "USDT",
        "name": "Tether USD",
        "decimals": 6
      }
    },
    {
      "id": "tx-uuid-2",
      "transactionType": "deposit",
      "status": "PENDING",
      "amount": "5.0",
      "createdAt": "2025-03-16T13:00:00Z",
      "updatedAt": "2025-03-16T13:00:00Z",
      "txHash": null,
      "networkType": "ERC20",
      "contractAddress": "0x...",
      "address": "0x123abc...",
      "token": {
        "networkType": "ERC20",
        "contractAddress": "0x...",
        "symbol": "USDT",
        "name": "Tether USD",
        "decimals": 6
      }
    }
  ]
}

Fetch Wallet Balance

await client.fetchWalletBalance('0x456def...', 'ERC20', '0x...');

Response:

{
  "address": "0x456def...",
  "networkType": "ERC20",
  "contractAddress": "0x...",
  "token": {
    "symbol": "USDT",
    "name": "Tether USD",
    "decimals": 6
  },
  "balance": {
    "raw": "10500000",
    "formatted": "10.5"
  }
}

Webhook Notifications

Sagapay uses webhooks to notify your application when events happen in your account. Each webhook notification contains information about the triggering event and transaction.

Webhook Payload Structure

When Sagapay sends a webhook to your endpoint, it will include the following payload:

{
  "id": "transaction-uuid",
  "type": "deposit|withdrawal",
  "status": "PENDING|PROCESSING|COMPLETED|FAILED|CANCELLED",
  "address": "0x123abc...",
  "networkType": "ERC20|BEP20|TRC20|POLYGON|SOLANA",
  "amount": "10.5",
  "udf": "your-optional-user-defined-field",
  "txHash": "0xabc123...",
  "timestamp": "2025-03-16T14:30:00Z"
}

Best Practices for Handling Webhooks

• Implement idempotency to handle duplicate webhook notifications
• Return a 200 status code promptly to acknowledge receipt
• Process webhook data asynchronously if business logic is complex
• Store webhook data for reconciliation and debugging purposes

Error Handling

try {
    await client.createDeposit(params);
} catch (error) {
    console.error(error.message);
}

Error Response:

{
    "error": "INVALID_AMOUNT",
    "message": "Invalid amount format",
    "data": {
        "field": "amount",
        "value": "-1.5"
    }
}

Mainnet Tokens (Use '0')

• BNB (BEP20)
• ETH (ERC20)
• MATIC (POLYGON)
• TRX (TRC20)
• SOL (SOLANA)

Token Contracts (example)

• USDT BEP20: 0x55d398326f99059fF775485246999027B3197955
• USDT ERC20: 0xdAC17F958D2ee523a2206206994597C13D831ec7
• USDT POLYGON: 0xc2132D05D31c914a87C6611C10748AEb04B58e8F
• USDT TRC20: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
• USDT SOLANA: Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB

Transaction States

• PENDING
• PROCESSING
• COMPLETED
• FAILED
• CANCELLED

Rate Limits

• /create-deposit: 10 requests per minute
• /create-withdrawal: 10 requests per minute
• /check-transaction-status: 60 requests per minute
• /fetch-wallet-balance: 100 requests per minute
• IPN retries: 10 attempts max
• Request timeout: 30 seconds

Types

type NetworkType = 'ERC20' | 'BEP20' | 'TRC20' | 'POLYGON' | 'SOLANA';
type TransactionStatus = 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
type AddressType = 'TEMPORARY' | 'PERMANENT';
type TransactionType = 'deposit' | 'withdrawal';

interface Token {
    networkType: NetworkType;
    contractAddress: string;
    symbol: string;
    name: string;
    decimals: number;
}

interface Balance {
    raw: string;
    formatted: string;
}