Einführung in serverseitige SDKs

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 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.

# Available as a gem
sudo gem install stripe

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

Nach Abschluss der Installation müssen Sie Stripe initialisieren:

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

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:

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="John 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 https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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:

customer = Stripe::Customer.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.

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:

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

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

paymentIntent = Stripe::PaymentIntent.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:

{
  "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:

paymentIntentList = Stripe::PaymentIntent.list({ limit: 3 })
for pi in paymentIntentList.data do
  puts pi.amount
end

Sie können auch die automatische Paginierung verwenden, um alle Ergebnisse zu durchlaufen.

Erweiterung der Antworten

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

• Rufen Sie einen PaymentIntent ab und erweitern Sie die zugehörige PaymentMethod.
  Command Line

  cURL

  curl -G https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}} \
    -u "
  sk_test_BQokikJOvBiI2HlWgH4olfQ2
  :" \
    -d "expand[]"=payment_method

• Rufen Sie eine Checkout-Sitzung ab und fügen Sie die Eigenschaft line_items hinzu.
  Command Line

  cURL

  curl -G https://api.stripe.com/v1/checkout/sessions/{{SESSION_ID}} \
    -u "
  sk_test_BQokikJOvBiI2HlWgH4olfQ2
  :" \
    -d "expand[]"=line_items

Erfahren Sie mehr über die Erweiterung von Antworten.

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 oder direkt mit Code wie dem folgenden:

customer = Stripe::Customer.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.
• Stellen Sie Anfragen für Ihre verbundenen Konten.
• Geben Sie Idempotenz-Schlüssel an.

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.

begin
  Stripe::PaymentIntent.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.

Funktionen für die private Vorschau

Stripe führt regelmäßig Funktionen für die private Vorschau ein, mit denen neue Eigenschaften oder Parameter eingeführt werden, die nicht sofort öffentlich sind. Dynamisch typisierte SDKs (PHP, Node, Ruby, Python) unterstützen diese automatisch. Verwenden Sie für stark typisierte SDKs (Java, .NET, Go) den folgenden Code, es sei denn, sie werden in einer Beta-Version unterstützt.

Nicht dokumentierte Parameter senden:

CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("jenny.rosen@example.com")
    .putExtraParam("secret_feature_enabled", "true")
    .build();

client.customers().create(params);

Zugriff auf nicht dokumentierte Felder:

final Customer customer = client.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:

Client- und Service-Muster

Für einige SDKs haben wir ein Client- und Service-Muster eingeführt, das die Art und Weise ändert, wie Sie Vorgänge ausführen. Dieses neue dienstbasierte Muster ermöglicht Ihnen das Erstellen von Mock-Objekten ohne statische Methoden und ermöglicht den gleichzeitigen Betrieb mehrerer Clientinstanzen mit unterschiedlicher Konfiguration.

Wenn Sie Code, der auf ältere Versionen dieser Bibliotheken abzielt, mit ressourcenbasierten Mustern vergleichen, sehen die Aufrufe möglicherweise anders aus.

Beta-Versionen

Wir bieten Beta-SDKs an, die durch das Dateinamenssuffix beta oder b identifiziert werden können, z. B 5.1.0-beta.3 oder 5.1.0b3. Sie geben Ihnen Zugriff auf Produkte und Funktionen, die sich in der Entwicklung befinden, und ermöglichen es Ihnen, uns Feedback zu senden, bevor diese allgemein verfügbar sind.

Der Zugriff auf die Beta-SDK-Versionen erfolgt über die Datei readme.md des jeweiligen GitHub-Repositorys.