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

$3

``bash
npm install @caspay/sdk


or


yarn add @caspay/sdk
`

$3

`html

`

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

📚 Quick Start

$3

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

#### React / Next.js

`typescript
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

`html


Pay 10 CSPR


`

$3

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

`typescript
// 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

$3

`typescript
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)
});
`

$3

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

📚 API Reference

$3

#### caspay.wallet.connect()

Connect to Casper Wallet extension.

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

#### caspay.wallet.disconnect()

Disconnect from wallet.

`typescript
await caspay.wallet.disconnect();
`

#### caspay.wallet.getAddress()

Get current connected wallet address.

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

#### caspay.wallet.getInfo()

Get cached wallet connection info (synchronous).

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

#### caspay.wallet.getState()

Get complete wallet state (asynchronous).

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

$3

#### caspay.payments.makePayment(params) - Full Management

Make a payment with full wallet & transfer management.

Parameters:

`typescript
{
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:

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

Example:

`typescript
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:

`typescript
{
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:

`typescript
{
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:

`typescript
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).

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

$3

#### caspay.subscriptions.checkStatus(params)

Check subscription status for a subscriber.

Parameters:

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

Returns:

`typescript
{
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:

`typescript
// 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:

`typescript
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
}
`

$3

- 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

$3

`typescript
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:

`typescript
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: support@caspay.link
- Issues: GitHub Issues

---

Made with ❤️ by CasPay Team