Integration Guide - API & SDK

npm install gasyard-sdk

const { GasyardSDK } = require('gasyard-sdk');

const gasyard = new GasyardSDK({
  apiKey: 'your-api-key',
  environment: 'production', // or 'sandbox'
  webhookSecret: 'your-webhook-secret'
});

// Accept payment from any blockchain
const payment = await gasyard.createPayment({
  amount: 99.99,
  currency: 'USD',
  acceptFrom: 'all_chains',    // Accept from any supported blockchain
  settleTo: 'base',            // Receive USDC on Base
  orderId: 'order_12345',
  customerInfo: {
    email: 'customer@example.com',
    phone: '+1234567890'
  },
  metadata: {
    productName: 'Premium Subscription',
    plan: 'annual'
  }
});

console.log('Payment URL:', payment.paymentUrl);
console.log('Payment ID:', payment.id);

// Accept from specific blockchains only
const payment = await gasyard.createPayment({
  amount: 299.99,
  acceptFrom: ['ethereum', 'arbitrum', 'polygon'],
  settleTo: 'arbitrum',
  allowPartialPayments: false,
  
  // Payment method preferences
  interfaces: ['web', 'mobile', 'qr', 'nfc'],
  
  // Time limits
  expiresAt: new Date(Date.now() + 30 * 60 * 1000), // 30 minutes
  
  // Auto-conversion
  convertTo: 'USDC',
  slippageTolerance: 0.5 // 0.5%
});

// Create programmable payment intent
const intent = await gasyard.createIntent({
  user: '0xUserAddress...',
  type: 'spending_card',
  
  // Spending limits
  maxPerTransaction: 50,
  maxTotal: 500,
  maxCount: 20,
  
  // Time restrictions
  validUntil: new Date('2024-12-31'),
  timeWindows: ['09:00-17:00'], // Business hours only
  
  // Category restrictions
  categories: ['food', 'transportation'],
  
  // Geographic limits
  geoFence: {
    latitude: 40.7128,
    longitude: -74.0060,
    radius: 10000 // 10km radius
  },
  
  // Distribution methods
  interfaces: ['nfc', 'qr', 'messaging'],
  
  metadata: {
    label: 'Employee expense card',
    department: 'Engineering'
  }
});

console.log('Intent ID:', intent.id);
console.log('NFC Data:', intent.nfcData);
console.log('QR Code:', intent.qrCode);

const subscription = await gasyard.createSubscription({
  amount: 29.99,
  interval: 'monthly',
  intervalCount: 1,
  
  // Trial period
  trialPeriodDays: 14,
  
  // Billing settings
  acceptFrom: 'all_chains',
  settleTo: 'base',
  currency: 'USD',
  
  // Customer info
  customer: {
    id: 'customer_123',
    email: 'user@example.com'
  },
  
  // Subscription metadata
  metadata: {
    plan: 'premium',
    features: ['api_access', 'priority_support']
  }
});

// Check user vault balance
const balance = await gasyard.getVaultBalance('0xUserAddress...');
console.log('USD Balance:', balance.usd);
console.log('Available:', balance.available);
console.log('Pending:', balance.pending);

// Deposit to vault
const deposit = await gasyard.depositToVault({
  userAddress: '0xUserAddress...',
  amount: 1000,
  sourceChain: 'ethereum',
  token: 'USDC'
});

// Withdraw from vault
const withdrawal = await gasyard.withdrawFromVault({
  userAddress: '0xUserAddress...',
  amount: 500,
  destinationChain: 'arbitrum',
  destinationAddress: '0xDestination...'
});

// Send payment intent via SMS/WhatsApp
const messagePayment = await gasyard.sendPaymentMessage({
  amount: 50,
  recipient: {
    phone: '+1234567890',
    name: 'John Doe'
  },
  sender: {
    name: 'Alice Smith',
    phone: '+0987654321'
  },
  message: 'Payment for dinner last night',
  platform: 'sms' // or 'whatsapp', 'telegram'
});

// Send gift card via email
const emailGift = await gasyard.sendGiftCardEmail({
  amount: 100,
  recipient: {
    email: 'recipient@example.com',
    name: 'Birthday Person'
  },
  sender: {
    name: 'Gift Giver',
    email: 'sender@example.com'
  },
  message: 'Happy Birthday!',
  template: 'birthday_card'
});

try {
  const payment = await gasyard.createPayment({
    amount: 99.99,
    acceptFrom: 'all_chains',
    settleTo: 'base'
  });
} catch (error) {
  if (error.code === 'INSUFFICIENT_BALANCE') {
    // Handle insufficient balance
    console.log('User needs to deposit more funds');
  } else if (error.code === 'INVALID_NETWORK') {
    // Handle unsupported network
    console.log('Requested network not supported');
  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Handle rate limiting
    console.log('Too many requests, please retry later');
  }
}

const gasyardTest = new GasyardSDK({
  apiKey: 'test_api_key',
  environment: 'sandbox',
  webhookSecret: 'test_webhook_secret'
});

// Create test payment
const testPayment = await gasyardTest.createPayment({
  amount: 10,
  acceptFrom: ['ethereum_testnet'],
  settleTo: 'base_testnet'
});