opengig-stripe/ReadMe.md

A wrapper for Stripe payment services with support for checkout and payment intents

# Stripe Payment Wrapper

A TypeScript wrapper for Stripe payment services that simplifies working with Checkout Sessions and Payment Intents.

## Features

- 🛒 Easy-to-use Stripe Checkout session creation
- 💳 Simplified Payment Intent management
- 🔒 Type-safe interfaces
- 💰 Support for subscriptions and one-time payments
- 🌐 Currency customization
- 📦 Metadata support

## Installation

```bash
npm install stripe-payment-wrapper
```

## Quick Start

```typescript
import { createStripeClient } from 'stripe-payment-wrapper';

const stripe = createStripeClient('your_stripe_secret_key');

// Create a checkout session
const checkoutSession = await stripe.checkout.createPaymentSession({
  priceId: 'price_H5ggYwtDq4fbrJ',
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel'
});

// Create a payment intent
const paymentIntent = await stripe.paymentIntent.create({
  amount: 2000, // $20.00
  currency: 'usd'
});
```

## Usage Examples

### Checkout Sessions

#### Create a Subscription Checkout

```typescript
const session = await stripe.checkout.createPaymentSession({
  priceId: 'price_H5ggYwtDq4fbrJ',
  customerId: 'cus_123456',
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  mode: 'subscription',
  quantity: 1,
  metadata: {
    orderId: '6735'
  }
});
```

#### Create a One-Time Payment Checkout

```typescript
const session = await stripe.checkout.createOneTimePaymentSession({
  amount: 2000, // $20.00
  currency: 'usd',
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  metadata: {
    orderId: '6735'
  }
});
```

### Payment Intents

#### Create a Payment Intent

```typescript
const intent = await stripe.paymentIntent.create({
  amount: 2000, // $20.00
  currency: 'usd',
  customerId: 'cus_123456',
  metadata: {
    orderId: '6735'
  }
});
```

#### Confirm a Payment Intent

```typescript
const confirmedIntent = await stripe.paymentIntent.confirm(
  'pi_123456',
  'pm_123456'
);
```

#### Retrieve a Payment Intent

```typescript
const intent = await stripe.paymentIntent.retrieve('pi_123456');
```

#### Update a Payment Intent

```typescript
const updatedIntent = await stripe.paymentIntent.update('pi_123456', {
  metadata: {
    status: 'processed'
  }
});
```

#### Cancel a Payment Intent

```typescript
const cancelledIntent = await stripe.paymentIntent.cancel('pi_123456');
```

## API Reference

### StripeCheckout

#### createPaymentSession(options)
- `priceId`: string - Stripe Price ID
- `customerId?`: string - Optional Stripe Customer ID
- `successUrl`: string - URL to redirect after successful payment
- `cancelUrl`: string - URL to redirect after cancelled payment
- `mode?`: 'subscription' | 'payment' (default: 'subscription')
- `quantity?`: number (default: 1)
- `metadata?`: Record<string, string>

#### createOneTimePaymentSession(options)
- `amount`: number - Amount in cents
- `currency?`: string (default: 'usd')
- `successUrl`: string
- `cancelUrl`: string
- `metadata?`: Record<string, string>

### StripePaymentIntent

#### create(options)
- `amount`: number - Amount in dollars
- `currency?`: string (default: 'usd')
- `customerId?`: string
- `metadata?`: Record<string, string>

#### confirm(paymentIntentId, paymentMethodId?)
- `paymentIntentId`: string
- `paymentMethodId?`: string

#### retrieve(paymentIntentId)
- `paymentIntentId`: string

#### update(paymentIntentId, data)
- `paymentIntentId`: string
- `data`: any

#### cancel(paymentIntentId)
- `paymentIntentId`: string

## Error Handling

```typescript
try {
  const session = await stripe.checkout.createPaymentSession({
    // options
  });
} catch (error) {
  if (error instanceof Error) {
    console.error('Error:', error.message);
  }
}
```

## Best Practices

1. **Environment Variables**: Store your Stripe secret key in environment variables
2. **Error Handling**: Always implement proper error handling
3. **Webhooks**: Set up webhooks to handle asynchronous events
4. **Testing**: Use Stripe's test mode keys for development
5. **Currency**: Always specify amounts in the smallest currency unit (cents for USD)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details