> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TypeScript
> Integrate Dodo Payments into your TypeScript and Node.js applications with type safety and modern async/await support
The TypeScript SDK provides convenient server-side access to the Dodo Payments REST API for TypeScript and JavaScript applications. It features comprehensive type definitions, error handling, retries, timeouts, and auto-pagination for seamless payment processing.
## Installation
Install the SDK using your package manager of choice:
```bash npm theme={null}
npm install dodopayments
```
```bash yarn theme={null}
yarn add dodopayments
```
```bash pnpm theme={null}
pnpm add dodopayments
```
## Quick Start
Initialize the client with your API key and start processing payments:
```javascript theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
environment: 'test_mode', // defaults to 'live_mode'
});
const checkoutSessionResponse = await client.checkoutSessions.create({
product_cart: [{ product_id: 'product_id', quantity: 1 }],
});
console.log(checkoutSessionResponse.session_id);
```
Always store your API keys securely using environment variables. Never commit them to version control or expose them in client-side code.
## Core Features
Full TypeScript support with comprehensive type definitions for all API endpoints
Automatic pagination for list responses makes working with large datasets effortless
Built-in error types with detailed messages for different failure scenarios
Configurable automatic retries with exponential backoff for transient errors
## Configuration
### Environment Variables
Set environment variables for secure configuration:
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```
### Timeout Configuration
Configure request timeouts globally or per-request:
```typescript theme={null}
// Configure default timeout for all requests (default is 1 minute)
const client = new DodoPayments({
timeout: 20 * 1000, // 20 seconds
});
// Override per-request
await client.checkoutSessions.create(
{ product_cart: [{ product_id: 'product_id', quantity: 1 }] },
{ timeout: 5 * 1000 },
);
```
### Retry Configuration
Configure automatic retry behavior:
```javascript theme={null}
// Configure default for all requests (default is 2 retries)
const client = new DodoPayments({
maxRetries: 0, // disable retries
});
// Override per-request
await client.checkoutSessions.create(
{ product_cart: [{ product_id: 'product_id', quantity: 1 }] },
{ maxRetries: 5 },
);
```
The SDK automatically retries requests that fail due to network errors or server issues (5xx responses) with exponential backoff.
## Common Operations
### Create a Checkout Session
Generate a checkout session for collecting payment information:
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: 'prod_123',
quantity: 1
}
],
return_url: 'https://yourdomain.com/return'
});
console.log('Redirect to:', session.checkout_url);
```
### Manage Customers
Create and retrieve customer information:
```typescript theme={null}
// Create a customer
const customer = await client.customers.create({
email: 'customer@example.com',
name: 'John Doe',
metadata: {
user_id: '12345'
}
});
// Retrieve customer
const retrieved = await client.customers.retrieve('cus_123');
console.log(`Customer: ${retrieved.name} (${retrieved.email})`);
```
### Handle Subscriptions
Create and manage recurring subscriptions:
```typescript theme={null}
// Create a subscription
const subscription = await client.subscriptions.create({
billing: {
country: 'US',
city: 'San Francisco',
state: 'CA',
street: '1 Market St',
zipcode: '94105',
},
customer: {
customer_id: 'cus_123', // or pass { email, name } to create a new customer
},
product_id: 'pdt_456',
quantity: 1,
});
// Charge an on-demand subscription
// product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
const chargeResponse = await client.subscriptions.charge(subscription.subscription_id, {
product_price: 2500,
});
// Retrieve subscription usage history (for metered subscriptions)
const usageHistory = await client.subscriptions.retrieveUsageHistory(subscription.subscription_id, {
start_date: '2024-01-01T00:00:00Z',
end_date: '2024-03-31T23:59:59Z',
});
```
`billing` memerlukan setidaknya kode negara ISO dua huruf. `customer` adalah gabungan dari `{ customer_id }` (untuk melampirkan pelanggan yang sudah ada) atau `{ email, name? }` (untuk membuat yang baru). `product_price` dinyatakan dalam denominasi mata uang terendah.
## Penagihan Berdasarkan Penggunaan
### Memasukkan Acara Penggunaan
Lacak acara kustom untuk penagihan berdasarkan penggunaan:
```typescript theme={null}
await client.usageEvents.ingest({
events: [
{
event_id: 'api_call_12345',
customer_id: 'cus_abc123',
event_name: 'api_request',
timestamp: '2024-01-15T10:30:00Z',
metadata: {
endpoint: '/api/v1/users',
method: 'GET',
tokens_used: '150'
}
}
]
});
```
Acara harus memiliki nilai `event_id` yang unik untuk idempoten. ID duplikat dalam permintaan yang sama akan ditolak, dan permintaan berikutnya dengan ID yang sudah ada akan diabaikan.
### Mengambil Acara Penggunaan
Ambil informasi rinci tentang acara penggunaan:
```typescript theme={null}
// Get a specific event
const event = await client.usageEvents.retrieve('api_call_12345');
// List events with filtering
const events = await client.usageEvents.list({
customer_id: 'cus_abc123',
event_name: 'api_request',
start: '2024-01-14T10:30:00Z',
end: '2024-01-15T10:30:00Z'
});
```
## Konfigurasi Proxy
Konfigurasikan pengaturan proxy untuk runtime yang berbeda:
### Node.js (menggunakan undici)
```typescript theme={null}
import DodoPayments from 'dodopayments';
import * as undici from 'undici';
const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new DodoPayments({
fetchOptions: {
dispatcher: proxyAgent,
},
});
```
### Bun
```typescript theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
fetchOptions: {
proxy: 'http://localhost:8888',
},
});
```
### Deno
```typescript theme={null}
import DodoPayments from 'npm:dodopayments';
const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new DodoPayments({
fetchOptions: {
client: httpClient,
},
});
```
## Logging
Kontrol tingkat verbosity log menggunakan variabel lingkungan atau opsi klien:
```typescript theme={null}
// Via client option
const client = new DodoPayments({
logLevel: 'debug', // Show all log messages
});
```
```bash theme={null}
# Via environment variable
export DODO_PAYMENTS_LOG=debug
```
**Tingkat log yang tersedia:**
* `'debug'` - Tampilkan pesan debug, info, peringatan, dan kesalahan
* `'info'` - Tampilkan pesan info, peringatan, dan kesalahan
* `'warn'` - Tampilkan peringatan dan kesalahan (default)
* `'error'` - Tampilkan hanya kesalahan
* `'off'` - Nonaktifkan semua log
Pada tingkat debug, semua permintaan dan respons HTTP dicatat, termasuk header dan body. Beberapa header autentikasi disunting, tetapi data sensitif dalam body mungkin masih terlihat.
## Migrasi dari Node.js SDK
Jika Anda meningkatkan dari SDK Node.js lama, TypeScript SDK menawarkan keamanan tipe yang lebih baik dan fitur berikut:
Pelajari cara bermigrasi dari Node.js SDK ke TypeScript SDK
## Auto-Pagination
Metode daftar dalam DodoPayments API dipaginasi. Anda dapat menggunakan sintaks `for await … of` untuk iterasi item di semua halaman:
```typescript theme={null}
async function fetchAllPayments() {
const allPayments = [];
// Automatically fetches more pages as needed.
for await (const paymentListResponse of client.payments.list()) {
allPayments.push(paymentListResponse);
}
return allPayments;
}
```
Sebagai alternatif, Anda dapat meminta satu halaman pada satu waktu:
```typescript theme={null}
let page = await client.payments.list();
for (const paymentListResponse of page.items) {
console.log(paymentListResponse);
}
// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
page = await page.getNextPage();
// ...
}
```
## Persyaratan
Runtime berikut didukung:
* Web browser (Chrome, Firefox, Safari, Edge, dan lainnya yang terbaru)
* Node.js 20 LTS atau yang lebih baru ([non-EOL](https://endoflife.date/nodejs))
* Deno v1.28.0 atau lebih tinggi
* Bun 1.0 atau lebih baru
* Cloudflare Workers
* Vercel Edge Runtime
* Jest 28 atau lebih dengan lingkungan `"node"`
* Nitro v2.6 atau lebih
TypeScript >= 4.9 didukung.
## Sumber Daya
Lihat kode sumber dan berkontribusi
Dokumentasi API lengkap
Mendapatkan bantuan dan terhubung dengan pengembang
Laporkan bug atau minta fitur
## Dukungan
Butuh bantuan dengan TypeScript SDK?
* **Discord**: Bergabunglah dengan [server komunitas](https://discord.gg/bYqAp4ayYh) kami untuk dukungan real-time
* **Email**: Hubungi kami di [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Buka masalah di [repository](https://github.com/dodopayments/dodopayments-typescript)
## Berkontribusi
Kami menyambut kontribusi! Lihat [pedoman kontribusi](https://github.com/dodopayments/dodopayments-typescript/blob/main/CONTRIBUTING.md) untuk memulai.