> ## 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
> Integrieren Sie Dodo Payments in Ihre TypeScript- und Node.js-Anwendungen mit Typsicherheit und modernem Async/Await-Support
Das TypeScript SDK bietet bequemen serverseitigen Zugriff auf die Dodo Payments REST API für TypeScript- und JavaScript-Anwendungen. Es verfügt über umfassende Typdefinitionen, Fehlerbehandlung, Wiederholungen, Zeitüberschreitungen und automatische Seitenumbruch für nahtlose Zahlungsabwicklung.
## Installation
Installieren Sie das SDK mit dem Paketmanager Ihrer Wahl:
```bash npm theme={null}
npm install dodopayments
```
```bash yarn theme={null}
yarn add dodopayments
```
```bash pnpm theme={null}
pnpm add dodopayments
```
## Schnellstart
Initialisieren Sie den Client mit Ihrem API-Schlüssel und beginnen Sie mit der Zahlungsabwicklung:
```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);
```
Speichern Sie Ihre API-Schlüssel stets sicher über Umgebungsvariablen. Kommittieren Sie sie niemals in die Versionsverwaltung und setzen Sie sie nicht in clientseitigem Code ein.
## Kernfunktionen
Vollständige TypeScript-Unterstützung mit umfassenden Typdefinitionen für alle API-Endpunkte
Automatische Paginierung für Listenantworten erleichtert die Arbeit mit großen Datensätzen
Eingebaute Fehlertypen mit detaillierten Meldungen für verschiedene Fehlerfälle
Konfigurierbare automatische Wiederholungen mit exponentiellem Backoff für temporäre Fehler
## Konfiguration
### Umgebungsvariablen
Setzen Sie Umgebungsvariablen für eine sichere Konfiguration:
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```
### Zeitüberschreitungs-Konfiguration
Konfigurieren Sie Zeitüberschreitungen für Anfragen global oder pro Anfrage:
```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 },
);
```
### Wiederholungs-Konfiguration
Konfigurieren Sie das Verhalten automatischer Wiederholungen:
```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 },
);
```
Das SDK wiederholt automatisch Anfragen, die aufgrund von Netzwerkfehlern oder Serverproblemen (5xx-Antworten) fehlschlagen, mit exponentiellem Backoff.
## Häufige Operationen
### Erstellen einer Checkout-Sitzung
Generieren Sie eine Checkout-Sitzung zur Erfassung von Zahlungsinformationen:
```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);
```
### Kunden verwalten
Erstellen und Abrufen von Kundeninformationen:
```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})`);
```
### Abonnements verwalten
Erstellen und verwalten Sie wiederkehrende Abonnements:
```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` erfordert mindestens den zweistelligen ISO-Ländercode. `customer` ist eine Vereinigung von `{ customer_id }` (um einen bestehenden Kunden anzufügen) oder `{ email, name? }` (um einen neuen zu erstellen). `product_price` wird in der niedrigsten Währungsdenomination angegeben.
## Verbrauchsbasierte Abrechnung
### Nutzung von Ereignissen erfassen
Verfolgen Sie benutzerdefinierte Ereignisse für verbrauchsbasierte Abrechnung:
```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'
}
}
]
});
```
Ereignisse müssen eindeutige `event_id`-Werte für Idempotenz haben. Doppelte IDs innerhalb derselben Anforderung werden abgelehnt und nachfolgende Anforderungen mit bestehenden IDs werden ignoriert.
### Nutzung von Ereignissen abrufen
Abrufen detaillierter Informationen über Nutzungereignisse:
```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'
});
```
## Proxy-Konfiguration
Proxy-Einstellungen für verschiedene Laufzeiten konfigurieren:
### Node.js (unter Verwendung von 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
Steuern Sie die Protokollierungstiefe mit Umgebungsvariablen oder Client-Optionen:
```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
```
**Verfügbare Protokollebene:**
* `'debug'` - Zeige Debug-Nachrichten, Infos, Warnungen und Fehler
* `'info'` - Zeige Infos, Warnungen und Fehler
* `'warn'` - Zeige Warnungen und Fehler (Standard)
* `'error'` - Zeige nur Fehler
* `'off'` - Deaktivieren Sie alle Logs
Auf der Debug-Ebene werden alle HTTP-Anfragen und -Antworten protokolliert, einschließlich Kopfzeilen und Körper. Einige Authentifizierungs-Header werden geschwärzt, aber sensible Daten in Körpern können weiterhin sichtbar sein.
## Migration von Node.js SDK
Wenn Sie vom veralteten Node.js SDK upgraden, bietet das TypeScript SDK verbesserte Typsicherheit und Funktionen:
Erfahren Sie, wie Sie vom Node.js SDK zum TypeScript SDK migrieren
## Automatische Paginierung
Listmethoden in der DodoPayments API sind paginiert. Sie können die `for await … of`-Syntax verwenden, um durch Elemente über alle Seiten hinweg zu iterieren:
```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;
}
```
Alternativ können Sie eine einzelne Seite nach der anderen anfordern:
```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();
// ...
}
```
## Anforderungen
Die folgenden Laufzeiten werden unterstützt:
* Webbrowser (Aktuelles Chrome, Firefox, Safari, Edge und mehr)
* Node.js 20 LTS oder später ([non-EOL](https://endoflife.date/nodejs)) Versionen
* Deno v1.28.0 oder höher
* Bun 1.0 oder später
* Cloudflare Workers
* Vercel Edge Runtime
* Jest 28 oder größer mit der `"node"` Umgebung
* Nitro v2.6 oder höher
TypeScript >= 4.9 wird unterstützt.
## Ressourcen
Quellcode ansehen und beitragen
Vollständige API-Dokumentation
Hilfe erhalten und mit Entwicklern vernetzen
Fehler melden oder Funktionen anfordern
## Support
Brauchen Sie Hilfe mit dem TypeScript SDK?
* **Discord**: Treten Sie unserem [Community-Server](https://discord.gg/bYqAp4ayYh) für Echtzeit-Support bei
* **E-Mail**: Kontaktieren Sie uns unter [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Öffnen Sie ein Problem im [Repository](https://github.com/dodopayments/dodopayments-typescript)
## Beitrag leisten
Beiträge sind willkommen! Schauen Sie sich die [Beiträge-Richtlinien](https://github.com/dodopayments/dodopayments-typescript/blob/main/CONTRIBUTING.md) an, um loszulegen.