CasPay SDK

Official JavaScript/TypeScript SDK for CasPay - Accept crypto payments with Casper blockchain.

🚀 Features

• Two Integration Modes:
  • Full Management: CasPay handles wallet connection, transfer & recording
  • Tracking Only: Merchant handles payment, CasPay tracks analytics
• Casper Wallet Integration: Seamless wallet connection and payments
• Subscription Management: Recurring payments with automatic tracking
• TypeScript Support: Full type definitions included
• Framework Agnostic: Works with React, Next.js, Vue, Vanilla JS, PHP

📦 Installation

NPM / Yarn (React, Next.js, Node.js)

npm install @caspay/sdk
# or
yarn add @caspay/sdk

CDN (PHP, HTML)

<script src="https://cdn.jsdelivr.net/npm/@caspay/[email protected]/dist/caspay.min.js"></script>

Note: Users only need to install Casper Wallet browser extension. No additional dependencies required.

📚 Quick Start

Mode 1: Full Management (CasPay Handles Everything)

CasPay SDK manages wallet connection, blockchain transfer, and payment recording.

React / Next.js

import CasPay from '@caspay/sdk';

const caspay = new CasPay({
  apiKey: 'cp_live_...',
  merchantId: 'MERCH_...',
  walletAddress: '01ab...', // Your wallet to receive payments
  network: 'testnet'
});

// One-time payment
const result = await caspay.payments.makePayment({
  productId: 'prod_abc123',
  amount: 10.5, // CSPR
});

// Subscription payment
const subResult = await caspay.payments.makePayment({
  subscriptionPlanId: 'plan_xyz789',
  amount: 29.99
});

PHP / Vanilla JS

<script src="https://cdn.jsdelivr.net/npm/@caspay/[email protected]/dist/caspay.min.js"></script>

<button id="payBtn">Pay 10 CSPR</button>

<script>
  const caspay = new CasPay({
    apiKey: 'cp_live_...',
    merchantId: 'MERCH_...',
    walletAddress: '01ab...',
    network: 'testnet'
  });

  document.getElementById('payBtn').onclick = async () => {
    const result = await caspay.payments.makePayment({
      productId: 'prod_abc',
      amount: 10
    });
  };
</script>

Mode 2: Tracking Only (Merchant Handles Payment)

Merchant integrates Casper Wallet separately, makes the payment, then records it with CasPay for analytics.

// After merchant processes the payment with their own wallet integration:

const result = await caspay.payments.recordPayment({
  senderAddress: '0145ab...', // Customer's wallet address
  transactionHash: 'abc123...', // Casper blockchain tx hash
  productId: 'prod_abc123',
  amount: 10.5,
  currency: 'CSPR'
});


// For subscriptions:
const subResult = await caspay.payments.recordSubscription({
  senderAddress: '0145ab...',
  transactionHash: 'xyz789...',
  subscriptionPlanId: 'plan_monthly',
  amount: 29.99,
  currency: 'CSPR'
});

🔧 Configuration

Constructor Options

const caspay = new CasPay({
  apiKey: string;         // Required: Your CasPay API key
  merchantId: string;     // Required: Your merchant ID
  walletAddress: string;  // Required: Merchant wallet to receive payments
  network?: 'mainnet' | 'testnet';  // Optional: Default is testnet
  baseUrl?: string;       // Optional: API base URL (for development)
});

Get API Keys

1. Sign up at caspay.link
2. Create and go the merchant page → API Keys
3. Generate a new API key

📚 API Reference

Wallet

caspay.wallet.connect()

Connect to Casper Wallet extension.

const address = await caspay.wallet.connect();
console.log('Connected:', address);

caspay.wallet.disconnect()

Disconnect from wallet.

await caspay.wallet.disconnect();

caspay.wallet.getAddress()

Get current connected wallet address.

const address = await caspay.wallet.getAddress();
console.log('Address:', address);

caspay.wallet.getInfo()

Get cached wallet connection info (synchronous).

const info = caspay.wallet.getInfo();
console.log('Connected:', info.isConnected);
console.log('Address:', info.address);

caspay.wallet.getState()

Get complete wallet state (asynchronous).

const state = await caspay.wallet.getState();
console.log('Connected:', state.connected);
console.log('Address:', state.address);
console.log('Locked:', state.locked);

Payments

caspay.payments.makePayment(params) - Full Management

Make a payment with full wallet & transfer management.

Parameters:

{
  productId?: string;              // Product ID (for one-time payments)
  subscriptionPlanId?: string;     // Subscription plan ID (for recurring)
  amount: number;                  // Payment amount in CSPR
  currency?: string;               // Currency code (default: CSPR)
}

Returns:

{
  success: boolean;
  transactionHash: string;
  payment?: PaymentResponse;       // If successfully recorded
  error?: string;                  // If payment failed
}

Example:

const result = await caspay.payments.makePayment({
  productId: 'prod_abc123',
  amount: 10.5
});

caspay.payments.recordPayment(params) - Tracking Only

Record a payment that was already processed by merchant.

Parameters:

{
  senderAddress: string;           // Sender's Casper wallet address
  transactionHash?: string;        // Casper transaction hash (optional)
  productId?: string;              // Product ID (for one-time payments)
  subscriptionPlanId?: string;     // Subscription plan ID (for recurring)
  amount: number;                  // Payment amount
  currency?: string;               // Currency code (default: USD)
}

Returns:

{
  success: boolean;
  payment: {
    id: string;
    transaction_hash: string;
    amount: number;
    token: string;
    status: string;
    invoice_number: string;
    created_at: string;
  };
  verification?: {
    verified: boolean;
    transaction_hash: string;
    amount: number;
  };
}

Example:

const result = await caspay.payments.recordPayment({
  senderAddress: '0145ab...',
  transactionHash: 'abc123...',
  productId: 'prod_abc123',
  amount: 10.5,
  currency: 'CSPR'
});

caspay.payments.recordSubscription(params) - Tracking Only

Record a subscription payment (alias for recordPayment with subscriptionPlanId).

const result = await caspay.payments.recordSubscription({
  senderAddress: '0145ab...',
  transactionHash: 'xyz789...',
  subscriptionPlanId: 'plan_monthly',
  amount: 29.99,
  currency: 'CSPR'
});

Subscriptions

caspay.subscriptions.checkStatus(params)

Check subscription status for a subscriber.

Parameters:

{
  subscriberAddress: string;  // Subscriber's wallet address
  planId?: string;            // Optional: Filter by specific plan
}

Returns:

{
  success: boolean;
  active: boolean;
  subscriptions?: Array<{
    id: string;
    plan_id: string;
    subscriber_address: string;
    status: string;
    current_period_start: string;
    current_period_end: string;
    created_at: string;
  }>;
  message?: string;
}

Example:

// Check all subscriptions for a subscriber
const status = await caspay.subscriptions.checkStatus({
  subscriberAddress: '0145ab...'
});

console.log('Active:', status.active);
console.log('Subscriptions:', status.subscriptions);

// Check specific plan
const planStatus = await caspay.subscriptions.checkStatus({
  subscriberAddress: '0145ab...',
  planId: 'plan_monthly'
});

🛠️ Error Handling

All SDK methods throw structured errors:

try {
  const payment = await caspay.payments.makePayment({...});
} catch (error) {
  console.error('Error:', error.error);   // Error message
  console.error('Code:', error.code);     // Error code
  console.error('Status:', error.status); // HTTP status
}

Common Error Codes

• INVALID_PARAMS - Missing or invalid parameters
• INVALID_API_KEY - Invalid API key
• WALLET_NOT_FOUND - Casper Wallet extension not installed
• WALLET_LOCKED - Wallet is locked
• CONNECTION_REJECTED - User rejected wallet connection
• TRANSFER_REJECTED - User rejected transaction
• NETWORK_ERROR - Network connection error
• VERIFICATION_FAILED - Transaction verification failed

Wallet Errors

try {
  await caspay.wallet.connect();
} catch (error) {
  if (error.code === 'WALLET_NOT_FOUND') {
    // Prompt user to install Casper Wallet
    window.open(error.installUrl, '_blank');
  } else if (error.code === 'WALLET_LOCKED') {
    alert('Please unlock your Casper Wallet');
  } else if (error.code === 'CONNECTION_REJECTED') {
    alert('Connection rejected by user');
  }
}

🌐 Environment Support

| Environment | Installation | Import | |-------------|--------------|--------| | React/Next.js | npm install @caspay/sdk | import CasPay from '@caspay/sdk' | | Node.js | npm install @caspay/sdk | const CasPay = require('@caspay/sdk') | | PHP/Vanilla JS | CDN script tag | window.CasPay |

📦 TypeScript Support

Full TypeScript support with type definitions included:

import CasPay, { 
  MakePaymentParams, 
  MakePaymentResult,
  PaymentCreateParams,
  PaymentResponse,
  SubscriptionCheckParams,
  SubscriptionCheckResponse,
  WalletState
} from '@caspay/sdk';

const params: MakePaymentParams = {
  productId: 'prod_abc',
  amount: 10.5
};

const result: MakePaymentResult = await caspay.payments.makePayment(params);

🎯 Integration Modes Comparison

| Feature | Full Management | Tracking Only | |---------|----------------|---------------| | Wallet Integration | ✅ CasPay SDK | ❌ Merchant implements | | Blockchain Transfer | ✅ CasPay SDK | ❌ Merchant handles | | Payment Recording | ✅ Automatic | ✅ Manual via SDK | | Analytics Dashboard | ✅ Yes | ✅ Yes | | Subscription Tracking | ✅ Yes | ✅ Yes | | Best For | Simple integration | Custom wallet UX |

🔗 Links

• Documentation: docs.caspay.link
• Dashboard: caspay.link
• Demo: demo.caspay.link
• NPM: @caspay/sdk
• GitHub: dmrdvn/caspay-sdk

📄 License

MIT License - see LICENSE file for details.

🤝 Support

• Email: [email protected]
• Issues: GitHub Issues

Made with ❤️ by CasPay Team