dodopayments-checkout/README.md

A TypeScript library for embedding Dodo Payments checkout (overlay and inline).

# Dodo Payments Checkout

[![npm version](https://img.shields.io/npm/v/dodopayments-checkout.svg)](https://www.npmjs.com/package/dodopayments-checkout)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

A modern TypeScript library for embedding Dodo Payments checkout (overlay and inline) and listening to checkout events in real-time. Built with developer experience in mind.

## Features

- 🚀 TypeScript-first with full type definitions
- 🔄 Real-time event handling
- 🎨 Customizable themes (light/dark)
- 🔒 Secure and production-ready
- 📱 Responsive design
- 🌐 Cross-browser compatibility

## Resources

- 📚 [Overlay Checkout Documentation](https://docs.dodopayments.com/api-reference/overlay-checkout)
- 📚 [Inline Checkout Documentation](https://docs.dodopayments.com/developer-resources/inline-checkout) (Beta)
- 🎮 [Interactive Demo](https://atlas.dodopayments.com#overlay-checkout)
- 💻 [Demo Source Code](https://github.com/dodopayments/dodo-checkout-demo/blob/main/src/components/Home/OverlayCheckout.tsx)

## Installation

```bash
# Using npm
npm install dodopayments-checkout

# Using yarn
yarn add dodopayments-checkout

# Using pnpm
pnpm add dodopayments-checkout
```

## CDN

Load the library from [jsDelivr](https://www.jsdelivr.com/) using the published npm package:

```html
<script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
```

Replace `@latest` with a specific version if desired. This script creates a global `DodoPaymentsCheckout` object with the same API as the module import.

## Quick Start

### Overlay Checkout

```typescript
import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "live", // 'test' or 'live'
  displayType: "overlay", // default
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123" // Get this url from create checkout session api
});
```

### Inline Checkout (Beta)

```typescript
import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK with inline display type
DodoPayments.Initialize({
  mode: "live",
  displayType: "inline", // Beta
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open inline checkout in a specific element
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  elementId: "checkout-container" // ID of the element where checkout should be embedded
});
```

```html
<!-- Your HTML -->
<div id="checkout-container"></div>
```

## API Reference

### Initialization

```typescript
DodoPayments.Initialize({
  mode: "test" | "live",
  displayType?: "overlay" | "inline", // "overlay" is default, "inline" is beta
  onEvent: (event: CheckoutEvent) => void,
});
```

### Checkout Methods

#### Open Checkout

```typescript
// Overlay checkout (default)
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

// Inline checkout (beta) - requires elementId
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  elementId: "checkout-container" // Required for inline checkout
});
```

#### Close Checkout

```typescript
DodoPayments.Checkout.close();
```

#### Check Status

```typescript
const isOpen = DodoPayments.Checkout.isOpen();
```

### Event Types

| Event                                 | Description                      |
| ------------------------------------- | -------------------------------- |
| `checkout.opened`                     | Checkout overlay has been opened |
| `checkout.payment_page_opened`        | Payment page has been displayed  |
| `checkout.customer_details_submitted` | Customer and billing details     |
| `checkout.closed`                     | Checkout has been closed         |
| `checkout.error`                      | An error occurred                |
| `checkout.redirect`                   | Checkout will perform a redirect |
| `checkout.breakdown`                  | Checkout pricing breakdown (subtotal, tax, discount, total) |

## TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions. All public APIs are fully typed for better developer experience.

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- IE11+

## Support

For support, please:

1. Check our [documentation](https://docs.dodopayments.com)
2. Contact our support team at support@dodopayments.com