# Einführung in serverseitige SDKs

Erfahren Sie, wie Sie die serverseitigen SDKs von Stripe installieren und verwenden können.

Die serverseitigen SDKs von Stripe reduzieren den Arbeitsaufwand für die Verwendung unserer REST-APIs. Stripe-verwaltete SDKs sind für Ruby, PHP, Java, Python, Node, .NET und Go verfügbar. [Community-Bibliotheken](https://docs.stripe.com/sdks/community.md) sind auch für andere Serversprachen verfügbar.

## Installation und Einrichtung

Wählen Sie Ihre Sprache in der Sprachauswahl unten aus und befolgen Sie dann die Anweisungen, um das SDK zu installieren.

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```

Nach Abschluss der Installation müssen Sie Stripe initialisieren:

#### Ruby

```ruby
require 'stripe'
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
```

## API-Anfragen senden

Sie können Objekte mit der Stripe-API auf sechs Hauptarten bearbeiten: Erstellen, Aktualisieren, Löschen, Abrufen, Auflisten und Suchen. Die folgenden Beispiele zeigen anhand des `Customer`-Objekts jede der sechs Möglichkeiten:

#### Erstellen

Erstellen Sie einen Kunden mit dem Namen Peter Mustermann.

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "name=John Doe"
```

#### Ändern

Rufen Sie einen Kunden/eine Kundin mit einer bestimmten ID ab.

```curl
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "email=jdoe@example.com"
```

#### Löschen

Löschen Sie einen Kunden/eine Kundin mit einer bestimmten ID.

```curl
curl -X DELETE https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

#### Abrufen

Rufen Sie einen Kunden/eine Kundin mit einer bestimmten ID ab.

```curl
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

#### Liste

Listen Sie die 5 zuletzt erstellten Kundinnen/Kunden auf.

```curl
curl -G https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d limit=5
```

#### Suchen

Suchen Sie nach Kundinnen mit dem Namen Maria Musterfrau.

```curl
curl -G https://api.stripe.com/v1/customers/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=name:'Jane Doe'"
```

API-Anfragen können verschiedene Arten von Parametern enthalten. So erstellen Sie beispielsweise einen Kunden/eine Kundin mit `name` (einer Zeichenfolge), `address` (einem Objekt) und `preferred_locales` (einer Liste):

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "name=John Doe" \
  -d "address[country]=US" \
  -d "address[city]=San Fransisco" \
  -d "preferred_locales[]=EN" \
  -d "preferred_locales[]=FR"
```

Wenn Sie ein Objekt aktualisieren, können Sie einige seiner Eigenschaften löschen. Senden Sie für dynamisch typisierte Sprachen eine leere Zeichenfolge. Verwenden Sie für stark typisierte Sprachen bestimmte Konstanten. So löschen Sie zum Beispiel den `name` (eine Zeichenfolge) und die `metadata` (einen Hash von Schlüssel-Wert-Paaren) eines Kunden/einer Kundin:

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
customer = client.v1.customers.update('{{CUSTOMER_ID}}', {
  name: '',
  metadata: '',
})
```

In diesem Beispiel werden alle Metadaten gelöscht, Sie können jedoch auch einzelne Schlüssel löschen. Weitere Informationen zur Verwaltung von Metadaten finden Sie in unserem [Metadaten-Leitfaden](https://docs.stripe.com/metadata.md).

## Auf die Antwort der API zugreifen

Jedes Mal, wenn Sie eine API Anfrage stellen, sendet Stripe Ihnen eine Antwort zurück.

Wenn Sie ein Objekt erstellen, abrufen oder aktualisieren, erhalten Sie das Objekt selbst zurück:

```json
{
  "id": "pi_001",
  "object": "payment_intent",
  "amount": 1099,
  "currency": "usd",
  /* ... */
}
```

Verwenden Sie eine Variable, um auf die Eigenschaften dieses Objekts zuzugreifen:

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
paymentIntent = client.v1.payment_intents.retrieve('{{PAYMENT_INTENT_ID}}')
puts paymentIntent.amount
```

Wenn Sie Objekte auflisten oder suchen, erhalten Sie ein `List`-Objekt zurück, das ein `data`-Array mit den angeforderten Objekten enthält:

```json
{
  "object": "list",
  "data": [
    {
      "id": "pi_003",
      "object": "payment_intent",
      "amount": 4200,
      "currency": "usd",
      /* ... */
    },
    {
      "id": "pi_002",
      "object": "payment_intent",
      "amount": 2100,
      "currency": "usd",
      "payment_method_types": [ "link" ],
      /* ... */
    }
  ],
  "has_more": true,
  "url": "/v1/payment_intents"
}
```

Verwenden Sie eine Schleife für das `data`-Array, um auf die Eigenschaften jedes Objekts zuzugreifen:

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
paymentIntentList = client.v1.payment_intents.list({ limit: 3 })
for pi in paymentIntentList.data do
  puts pi.amount
end
```

Sie können auch [auto-pagination](https://docs.stripe.com/pagination.md#auto-pagination) verwenden, um über alle Ergebnisse zu iterieren.

## Erweiterung der Antworten

Einige Eigenschaften können erweitert oder einbezogen werden, d.&nbsp;h., Sie können sie mithilfe des Parameters `expand` zurückgeben. Beispiel:

- Rufen Sie einen PaymentIntent ab und erweitern Sie die zugehörige PaymentMethod.
  ```curl
  curl -G https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}} \
    -u "<<YOUR_SECRET_KEY>>:" \
    -d "expand[]=payment_method"
  ```
- Rufen Sie eine Checkout-Sitzung ab und fügen Sie die Eigenschaft `line_items` hinzu.
  ```curl
  curl -G https://api.stripe.com/v1/checkout/sessions/{{SESSION_ID}} \
    -u "<<YOUR_SECRET_KEY>>:" \
    -d "expand[]=line_items"
  ```

Erfahren Sie mehr über die [Erweiterung von Antworten](https://docs.stripe.com/expand.md).

## Anfrage-ID abrufen

Jeder API-Anfrage ist eine eindeutige Anfrage-ID (`req_xxx`) zugeordnet. Sie können sie verwenden, um die Anfrage im Dashboard zu überprüfen, um die von Stripe empfangenen Parameter anzuzeigen oder um sie an den Stripe-Support weiterzuleiten, wenn Sie ein Problem lösen müssen.

Sie finden die IDs in Ihren [Dashboard-Protokollen](https://dashboard.stripe.com/test/workbench/logs) oder direkt mit Code wie dem folgenden:

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
customer = client.v1.customers.create({ name: 'John Doe', })
puts customer.last_response.request_id
```

## Zusätzliche Anfrageoptionen festlegen

Beim Senden von API-Anfragen können Sie zusätzliche Anfrageoptionen für Folgendes festlegen:

- [Legen Sie eine bestimmte API Version fest.](https://docs.stripe.com/sdks/set-version.md)
- [Stellen Sie Anfragen für Ihre verbundenen Konten.](https://docs.stripe.com/connect/authentication.md)
- [Geben Sie Idempotenz-Schlüssel an.](https://docs.stripe.com/api/idempotent_requests.md)

## Fehlerbehebung

Jedes Server-SDK interpretiert Fehlerantworten von der Stripe-API als Ausnahmetypen, sodass Sie den Antwortstatus nicht selbst analysieren müssen. Verwenden Sie für jede Sprache geeignete Fehlerbehandlungskonventionen, um mit diesen Fehlern umzugehen.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
begin
  client.v1.payment_intents.create(params)
rescue Stripe::CardError => e
  puts "A payment error occurred: #{e.error.message}"
rescue Stripe::InvalidRequestError => e
  puts "An invalid request occurred."
rescue Stripe::StripeError => e
  puts "Another problem occurred, maybe unrelated to Stripe."
else
  puts "No error."
end
```

Erfahren Sie mehr über die [Fehlerbehebung](https://docs.stripe.com/error-handling.md).

## Nicht dokumentierte Parameter und Felder

In einigen Fällen können Parameter in einer API-Anfrage oder Felder in einer API-Antwort auftreten, die in den SDKs nicht verfügbar sind. Dies kann vorkommen, wenn sie nicht dokumentiert sind oder sich in der Vorschau befinden und Sie kein Vorschau-SDK verwenden. Befolgen Sie die folgenden Anweisungen, um diese Parameter zu senden oder auf diese Felder zuzugreifen.

### Nicht dokumentierte Parameter senden

Im folgenden Beispiel erstellen Sie eine/n `Kundin/Kunden` mit einem undokumentierten booleschen Parameter. Das Codebeispiel verwendet `secret_feature_enabled`, die von den SDKs nicht veröffentlicht wird.

#### Java

```java

// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
StripeClient stripeClient = new StripeClient("<<YOUR_SECRET_KEY>>");
CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("jenny.rosen@example.com")
    .putExtraParam("secret_feature_enabled", "true")
    .build();

stripeClient.v1().customers().create(params);
```

### Zugriff auf undokumentierte Felder

Im folgenden Beispiel lesen Sie ein undokumentiertes boolesches Feld für das `Kundenobjekt`. Das Codebeispiel verwendet `secret_feature_enabled`, die die SDKs nicht offenlegen.

#### Java

```java

// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
StripeClient stripeClient = new StripeClient("<<YOUR_SECRET_KEY>>");
final Customer customer = stripeClient.v1().customers().retrieve("cus_1234");
Boolean featureEnabled = customer.getRawJsonObject()
    .getAsJsonPrimitive("secret_feature_enabled")
    .getAsBoolean();
```

## Quellcode

Der Quellcode für jedes unserer Server-SDKs ist auf GitHub verfügbar:

| Sprache | Repository |
| --- | --- |
| **Ruby** | [`stripe-ruby`](https://github.com/stripe/stripe-ruby) |
| **PHP** | [`stripe-php`](https://github.com/stripe/stripe-php) |
| **Java** | [`stripe-Java`](https://github.com/stripe/stripe-java) |
| **Node** | [`stripe-node`](https://github.com/stripe/stripe-node) |
| **Python** | [`stripe-python`](https://github.com/stripe/stripe-python) |
| **.NET** | [`stripe-dotnet`](https://github.com/stripe/stripe-dotnet) |
| **Go** | [`stripe-go`](https://github.com/stripe/stripe-go) |

## StripeClient

Die `StripeClient`-Klasse fungiert als Einstiegspunkt, um Ressourcen zu entdecken und Anfragen an die Stripe-API zu stellen. Die Vorteile der Verwendung dieses Musters gegenüber dem älteren, das eine globale Konfiguration verwendete, sind:

- Sie können gleichzeitig mehrere Clients mit unterschiedlichen Konfigurationsoptionen (wie API-Schlüsseln) verwenden.
- Es ermöglicht einfacheres Mocking während des Testens, da `StripeClient` keine statischen Methoden verwendet.
- Keine zusätzlichen API-Aufrufe. In einigen Programmiersprachen musste man vor einer Aktualisierung oder einer Löschung zunächst einen Abruf durchführen. Bei Verwendung von `StripeClient` können Sie auf alle API-Endpoints mit einem einzigen Methodenaufruf zugreifen.

Das Node.js SDK hatte immer die `Stripe`-Klasse, die dem gleichen Muster folgte. Für die übrigen Programmiersprachen wurde das neue Muster in den folgenden SDK-Versionen eingeführt. Wenn Sie den Code vergleichen, der auf ältere Versionen dieser Bibliotheken mit dem alten Muster abzielt, könnten die Aufrufe unterschiedlich aussehen.

| Migrationsleitfäden | Veröffentlichung von StripeClient |
| --- | --- |
| [stripe-php-Migrationshandbuch](https://github.com/stripe/stripe-php/wiki/Migration-to-StripeClient-and-services-in-7.33.0) | 7.33.0 |
| [stripe-python-Migrationsleitfaden](https://github.com/stripe/stripe-python/wiki/Migration-guide-for-v8-\(StripeClient\)) | 8.0.0 |
| [stripe-java Migrationshandbuch](https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v23#stripeclient) | 23.0.0 |
| [stripe-ruby Migrationshandbuch](https://github.com/stripe/stripe-ruby/wiki/Migration-guide-for-v13) | 13.0.0 |
| [stripe-dotnet Migrationshandbuch](https://github.com/stripe/stripe-dotnet/blob/master/CHANGELOG.md#stripeclient) | 46.0.0 |
| [stripe-go Migrationshandbuch](https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client#migrating-from-global-configuration) | 82.1.0 |

## Öffentliche und private Vorschauversionen

Stripe verfügt über Funktionen in den [Phasen der öffentlichen und privaten Vorschau](https://docs.stripe.com/release-phases.md), auf die Sie über Versionen der SDKs mit dem Suffix [`beta` oder `b`](https://docs.stripe.com/sdks/versioning.md#public-preview-release-channel) bzw. [`alpha` oder `a`](https://docs.stripe.com/sdks/versioning.md#private-preview-release-channel) zugreifen können.