Shipy SDK for JavaScript/TypeScript

A modern, type-safe SDK for integrating with the Shipy Payment Gateway. Built with TypeScript, works with both JavaScript and TypeScript projects.

Features

• 🚀 TypeScript First: Full TypeScript support with type definitions
• 💳 Multiple Payment Methods: Support for credit card and mobile payments
• 🔒 Secure: Built-in callback verification
• 🎯 Zero Dependencies: Uses native fetch API
• 📦 Tree-shakeable: Only import what you need
• ✅ 100% Test Coverage: Fully tested with Jest

Installation

npm install shipy-sdk-js
# or
yarn add shipy-sdk-js
# or
pnpm add shipy-sdk-js

Quick Start

import { Shipy } from 'shipy-sdk-js';

// Initialize with your API key
const shipy = new Shipy('your-api-key');

// Create a credit card payment
const payment = await shipy.creditCard.pay({
  returnID: 'order123',
  usrIp: '127.0.0.1',
  amount: 100,
  usrName: 'John Doe',
  usrAddress: '123 Main St',
  usrPhone: '5551234567',
  usrEmail: '[email protected]',
  currency: 'TRY',
  pageLang: 'TR',
  mailLang: 'TR',
  installment: 0
});

// Redirect user to payment page
window.location.href = payment.link;

API Reference

Credit Card Payments

const payment = await shipy.creditCard.pay({
  // Required fields
  returnID: string | number,
  usrIp: string,
  usrName: string,
  usrAddress: string,
  usrPhone: string,
  usrEmail: string,
  amount: number,

  // Optional fields
  currency?: 'TRY' | 'USD' | 'EUR' | 'GBP',
  pageLang?: 'TR' | 'EN' | 'DE' | 'AR' | 'ES' | 'FR',
  mailLang?: 'TR' | 'EN',
  installment?: 0 | 3 | 6 | 9 | 12
});

Mobile Payments

const payment = await shipy.mobile.pay({
  // Required fields
  returnID: string | number,
  usrIp: string,
  usrName: string,
  usrAddress: string,
  usrPhone: string,
  usrEmail: string,
  amount: number
});

Event Handling

// Listen for payment success
shipy.creditCard.eventEmitter.on('payment.success', (data) => {
  console.log('Payment successful:', data);
});

// Listen for payment pending
shipy.creditCard.eventEmitter.on('payment.pending', (data) => {
  console.log('Payment pending:', data);
});

// Listen for errors
shipy.creditCard.eventEmitter.on('error', (error) => {
  console.error('Payment error:', error);
});

Callback Verification

// Verify callback data
const isValid = shipy.creditCard.verifyCallback({
  paymentID: string,
  returnID: string,
  paymentType: 'credit_card' | 'mobile' | 'eft',
  paymentAmount: number,
  paymentCurrency: string,
  paymentHash: string
});

Error Handling

try {
  const payment = await shipy.creditCard.pay({
    // ... payment details
  });
  
  if (payment.status === 'success') {
    window.location.href = payment.link;
  }
} catch (error) {
  console.error('Payment failed:', error.message);
}

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Build
pnpm build

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.