ZyPay Node.js SDK

A comprehensive Node.js SDK for integrating with ZyPay's blockchain payment processing platform. This SDK provides easy-to-use methods for handling payments, payins, payouts, and participant management.

Features

• Payments: Create and manage traditional payments
• Payins: Handle crypto payments with multiple blockchain support
• Payouts: Manage payouts to registered participants
• Participant Management: Register and manage payout participants
• Webhook Support: Verify and handle webhook events
• Health Monitoring: Check service status and health
• TypeScript Support: Full TypeScript definitions included
• Error Handling: Comprehensive error handling and logging

Installation

npm install @zypay/sdk

Quick Start

import { ZyPaySDK } from '@zypay/sdk'

const client = new ZyPaySDK({
  apiKey: 'your_api_key_here',
  environment: 'sandbox', // or 'production'
  webhookSecret: 'your_webhook_secret' // optional
})

// Test the connection
const health = await client.health.check()
console.log('SDK Status:', health.status)

// Create a new payment
const payment = await client.payments.create({
  amount: {
    value: 1000, // $10.00 in cents
    currency: 'USD'
  },
  customer: {
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe'
  },
  description: 'Test payment',
  metadata: {
    orderId: 'order_123',
    source: 'website'
  }
})

console.log('Payment created:', payment.id)
console.log('Status:', payment.status)

// Handle payment completion
if (payment.status === 'completed') {
  console.log('Payment successful!')
}

Configuration

Basic Configuration

const client = new ZyPaySDK({
  apiKey: 'your_api_key_here',
  environment: 'sandbox', // or 'production'
})

Advanced Configuration

const client = new ZyPaySDK({
  apiKey: 'your_api_key_here',
  environment: 'production',
  webhookSecret: 'your_webhook_secret',
  baseUrl: 'https://custom-api.zypay.app', // optional
  timeout: 30000, // optional, default: 30000ms
  debug: true // optional, default: false
})

API Reference

Payments

Create Payment

const payment = await client.payments.create({
  amount: { value: 1000, currency: 'USD' },
  customer: {
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe'
  },
  description: 'Test payment',
  metadata: { orderId: 'order_123' }
})

Get Payment

const payment = await client.payments.get('payment_123')

List Payments

const payments = await client.payments.list({
  page: 1,
  limit: 10,
  sortBy: 'createdAt',
  sortOrder: 'desc'
})

Cancel Payment

const payment = await client.payments.cancel('payment_123')

Refund Payment

const payment = await client.payments.refund('payment_123', {
  value: 500,
  currency: 'USD'
}, 'Customer requested partial refund')

Payins (Crypto Payments)

Process Payin Transaction

const payin = await client.payins.processTransaction({
  email: '[email protected]',
  blockchain: 'Ton',
  package_name: 'basic'
})

Get Payin Transaction

const payin = await client.payins.get('payin_123')
console.log('Payment address:', payin.to.wallet_address)
console.log('Status:', payin.status)

Simulate Payin Payment

const payin = await client.payins.simulatePayment()
console.log('Simulated payin:', payin.id)

List Payins

const payins = await client.payins.list({
  page: 1,
  limit: 10
})

Get Available Blockchains

const blockchains = await client.payins.getAvailableBlockchains()
console.log('Available blockchains:', blockchains)

Payouts

Register Participant

const participant = await client.payouts.registerParticipant({
  email: '[email protected]',
  firstName: 'John',
  lastName: 'Doe',
  walletAddress: '0x123...',
  blockchain: 'Ton'
})

Create Payout (Only for registered participants)

const payout = await client.payouts.create({
  amount: { value: 1000, currency: 'USD' },
  participantEmail: '[email protected]',
  description: 'Payout to participant',
  blockchain: 'Ton'
})

Get Payout

const payout = await client.payouts.get('payout_123')

List Payouts

const payouts = await client.payouts.list({
  page: 1,
  limit: 10
})

List Participants

const participants = await client.payouts.listParticipants({
  page: 1,
  limit: 10
})

Update Participant

const participant = await client.payouts.updateParticipant('[email protected]', {
  walletAddress: '0x456...',
  blockchain: 'BSC'
})

Check Participant Eligibility

const isEligible = await client.payouts.isParticipantEligible('[email protected]')
if (isEligible) {
  console.log('Participant can receive payouts')
}

Health Monitoring

Check Health

const health = await client.health.check()
console.log('Service status:', health.status)

Check if Healthy

const isHealthy = await client.health.isHealthy()
if (isHealthy) {
  console.log('Service is operational')
}

Get Detailed Health

const health = await client.health.getDetailed()
console.log('Database status:', health.details?.database)
console.log('Blockchain status:', health.details?.blockchain)

Webhooks

Verify Webhook Signature

const isValid = client.webhooks.verifySignature({
  signature: req.headers['x-zypay-signature'],
  timestamp: req.headers['x-zypay-timestamp'],
  payload: JSON.stringify(req.body)
})

Parse Webhook Event

const event = client.webhooks.parseEvent(req.body)
console.log('Event type:', event.type)

Handle Webhook Event

client.webhooks.handleEvent(event, {
  'payment.completed': (payment) => {
    console.log('Payment completed:', payment.id)
  },
  'payout.failed': (payout) => {
    console.log('Payout failed:', payout.id)
  }
})

Validate Webhook Timestamp

const isValid = client.webhooks.validateTimestamp(req.headers['x-zypay-timestamp'])

Error Handling

The SDK throws errors for various scenarios:

try {
  const payment = await client.payments.create(paymentData)
} catch (error) {
  if (error.message.includes('Failed to create payment')) {
    console.error('Payment creation failed:', error.message)
  }
}

Supported Blockchains

• Ton - The Open Network
• BSC - Binance Smart Chain
• Ethereum - Ethereum Mainnet
• Bitcoin - Bitcoin Network

Environment Variables

You can also configure the SDK using environment variables:

ZYPAY_API_KEY=your_api_key_here
ZYPAY_ENVIRONMENT=sandbox
ZYPAY_WEBHOOK_SECRET=your_webhook_secret
ZYPAY_BASE_URL=https://api.zypay.app
ZYPAY_TIMEOUT=30000
ZYPAY_DEBUG=true

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { ZyPaySDK, Payment, Payin, Payout, Participant } from '@zypay/sdk'

const client: ZyPaySDK = new ZyPaySDK(config)
const payment: Payment = await client.payments.create(paymentData)

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, email [email protected] or join our Discord community.

Changelog

See CHANGELOG.md for a list of changes and version history.