Payment SDK for blockchain-based payment system
npm install @dj-test/payment-sdkbash
pnpm add payment-sdk wagmi viem @tanstack/react-query
`
Quick Start
$3
`tsx
import { PaymentProvider, WalletProvider } from 'payment-sdk';
function App() {
return (
environment="production"
baseUrl={process.env.NEXT_PUBLIC_API_URL}
redirectUrl="https://yoursite.com/payment/success"
webhookUrl="https://yoursite.com/api/webhook/payment"
>
);
}
`
$3
`tsx
import { PayWithWallet } from 'payment-sdk';
function CheckoutPage() {
return (
amount="100"
coinId="USDC"
chainId={11155111} // Sepolia testnet
onSuccess={(txHash) => console.log('Success:', txHash)}
onError={(error) => console.error('Error:', error)}
/>
);
}
`
$3
`tsx
import { PayWithAddress } from 'payment-sdk';
function PaymentPage() {
return (
amount="100"
coinId="USDC"
chainId={11155111}
publicOrderId="order-uuid"
expiresAt="2025-01-04T15:30:00"
/>
);
}
`
$3
`tsx
import { useWallet } from 'payment-sdk';
function WalletComponent() {
const {
wallet,
isConnected,
connect,
disconnect,
connectors,
sendPayment,
} = useWallet();
return (
{!isConnected ? (
) : (
<>
Connected: {wallet?.address}
)}
);
}
`
$3
`tsx
import { useWalletAdapter, WalletTypes } from 'payment-sdk';
function MultiChainWallet() {
const {
wallet,
isConnected,
connect,
disconnect,
chainType,
balance,
sendPayment,
} = useWalletAdapter();
const connectEvm = () => {
connect(WalletTypes.EVM, 'injected'); // MetaMask
};
const connectTron = () => {
connect(WalletTypes.TRON, 'tronlink'); // TronLink
};
return (
{!isConnected ? (
<>
) : (
<>
Chain: {chainType}
Address: {wallet?.address}
Balance: {balance?.formatted} {balance?.symbol}
)}
);
}
`
$3
`tsx
import { PayWithWallet } from 'payment-sdk';
function TronPayment() {
return (
amount="100"
coinId="USDT"
chainId="mainnet" // Tron mainnet
onSuccess={(txHash) => console.log('Tron TX:', txHash)}
onError={(error) => console.error('Error:', error)}
/>
);
}
`
$3
`tsx
import { useWalletAdapter } from 'payment-sdk';
function AutoDetectPayment({ depositAddress }: { depositAddress: string }) {
// Automatically selects EVM or Tron adapter based on address format
// 0x... -> EVM adapter
// T... -> Tron adapter
const adapter = useWalletAdapter({ depositAddress });
return (
Detected Chain: {adapter.chainType}
);
}
`
Supported Networks
$3
- Ethereum Mainnet (1)
- Sepolia Testnet (11155111)
- Polygon Mainnet (137)
- Polygon Amoy Testnet (80002)
- Base Mainnet (8453)
- Base Sepolia (84532)
$3
- Tron Mainnet (mainnet)
- Tron Shasta Testnet (shasta)
- Tron Nile Testnet (nile)
Supported Wallets
$3
- Injected Wallets: MetaMask, Trust Wallet, Brave Wallet
- Desktop: Browser extensions (MetaMask, etc.)
- Mobile Web: In-app browsers + deep links (MetaMask app)
$3
- TronLink: Official Tron wallet extension
- TronLink Pro: Mobile wallet with WalletConnect support
Mobile Web Support
SDK follows Daimo Pay approach for mobile web:
- ✅ In-app browser detection: Auto-detects MetaMask in-app browser
- ✅ Deep link support: Opens MetaMask app from regular mobile browsers
- ✅ No WalletConnect needed: Lightweight solution without WC dependency
$3
Option 1: MetaMask In-App Browser (Recommended)
`
User opens your site in MetaMask app browser
→ SDK detects window.ethereum
→ Direct wallet connection works
`
Option 2: Regular Mobile Browser
`tsx
import { getConnectionStrategy, openMetaMaskDeepLink } from 'payment-sdk';
function ConnectButton() {
const strategy = getConnectionStrategy();
const handleConnect = () => {
if (strategy.type === 'deeplink') {
// Opens MetaMask app
openMetaMaskDeepLink();
} else if (strategy.type === 'injected') {
// Use wagmi connect
connect();
}
};
return ;
}
`
$3
`tsx
import {
isMobile,
isMetaMaskBrowser,
isMetaMaskAvailable,
shouldUseDeepLink,
} from 'payment-sdk';
// Check if on mobile device
const mobile = isMobile();
// Check if in MetaMask in-app browser
const inMetaMask = isMetaMaskBrowser();
// Check if MetaMask is available (extension or in-app)
const hasMetaMask = isMetaMaskAvailable();
// Determine if should use deep link
const useDeepLink = shouldUseDeepLink();
`
API Reference
$3
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| apiKey | string | Yes | Your API key |
| environment | 'production' \| 'sandbox' | Yes | Environment |
| baseUrl | string | No | Custom API URL |
| redirectUrl | string | Yes | Success redirect URL |
| webhookUrl | string | Yes | Webhook endpoint URL |
| timeout | number | No | Request timeout (default: 30000ms) |
$3
Returns:
- createOrder(params) - Create a new payment order
- isLoading - Loading state
- error - Error object
- order - Created order object
- errorMessage - User-friendly error message
$3
`tsx
const { order, isLoading, error, refetch } = useOrder(publicOrderId);
`
Returns order details and allows manual refresh.
$3
`tsx
import { validation } from '@your-company/payment-sdk';
// Validate withdrawal address
const result = validation.validateWithdrawalAddress(fromAddress, toAddress);
if (!result.valid) {
console.error(result.error);
}
// Validate Ethereum address format
const isValid = validation.isValidEthereumAddress(address);
`
Security Features
$3
- Uses UUID for public order IDs (unpredictable)
- Internal database IDs remain hidden
$3
- Prevents sending to your own wallet address
- Validates address format
- Validates amount
$3
- HTTPS required for production
- API key authentication
- Webhook signature verification
Payment Flow
1. Create Order: Merchant calls createOrder()
2. Redirect: User redirected to payment page
3. Payment: User sends crypto to wallet address
4. Monitor: System monitors blockchain for deposit
5. Complete: Webhook sent to merchant, user redirected to success page
Environment Variables
`env
NEXT_PUBLIC_API_URL=https://api.yourpayment.com
NEXT_PUBLIC_API_KEY=your-api-key-here
NEXT_PUBLIC_REDIRECT_URL=https://yoursite.com/payment/success
NEXT_PUBLIC_WEBHOOK_URL=https://yoursite.com/api/webhook/payment
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your-walletconnect-project-id
``