Introduction aux SDK côté serveur

Les SDK Stripe côté serveur réduisent la quantité de travail nécessaire à l’utilisation de nos API REST. Les SDK maintenus par Stripe sont disponibles pour Ruby, PHP, Java, Python, Node, .NET et Go. Des bibliothèques de la communauté sont également disponibles pour d’autres langages de serveur.

Installation et configuration

Sélectionnez un langage dans le sélecteur ci-dessous, puis suivez les instructions pour installer le SDK.

# Available as a gem
sudo gem install stripe

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

Une fois l’installation terminée, vous devez initialiser Stripe :

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

Envoyer des requêtes API

Vous pouvez manipuler des objets avec l’API Stripe de six manières principales : créer, mettre à jour, supprimer, récupérer, lister et rechercher. Les exemples suivants illustrent chacun des six modes d’utilisation de l’objet Customer :

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="John Doe"

Les requêtes API peuvent contenir différents types de paramètres. Par exemple, voici comment créer un client avec les paramètres name (une chaîne), address (un objet) et preferred_locales (une 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

Lorsque vous modifiez un objet, vous pouvez effacer certaines de ses propriétés. Pour les langages typés dynamiquement, envoyez une chaîne vide. Pour les langages fortement typés, utilisez des constantes spécifiques. Par exemple, voici comment effacer les propriétés name (une chaîne) et metadata (un hachage de paires clé-valeur) d’un client :

customer = Stripe::Customer.update(
'{{CUSTOMER_ID}}', {
  name: '',
  metadata: '',
})

Cet exemple efface toutes les métadonnées, mais vous pouvez également effacer des clés individuelles. Pour en savoir plus sur la gestion des métadonnées, consultez notre guide des métadonnées.

Accéder à la réponse API

Chaque fois que vous effectuez une requête API, Stripe vous renvoie une réponse.

Si vous créez, récupérez ou modifiez un objet, vous obtenez l’objet lui-même :

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

Utilisez une variable pour accéder aux propriétés de cet objet :

paymentIntent = Stripe::PaymentIntent.retrieve('{{PAYMENT_INTENT_ID}}')
puts paymentIntent.amount

Pour lister ou rechercher des objets, vous récupérez un objet List contenant une matrice data avec les objets demandés :

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

Utilisez une boucle sur la data matrice pour accéder aux propriétés de chaque objet :

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

Vous pouvez également utiliser la pagination automatique pour itérer sur tous les résultats.

Développement des réponses

Certaines propriétés peuvent être développées ou incluses, ce qui signifie que vous pouvez les renvoyer à l’aide du paramètre expand. Par exemple :

• Récupérez un PaymentIntent et développez l’objet PaymentMethod qui lui est associé.
  Command Line

  Sélectionner une langue

  cURL

  Stripe CLI

  Ruby

  Python

  PHP

  Java

  Node

  Go

  .NET

  No results

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

• Récupérez une session Checkout et incluez la propriété line_items.
  Command Line

  Sélectionner une langue

  cURL

  Stripe CLI

  Ruby

  Python

  PHP

  Java

  Node

  Go

  .NET

  No results

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

En savoir plus sur le développement des réponses.

Récupérer l’ID de requête

Chaque requête API est associée à un ID de requête unique (req_xxx). Vous pouvez l’utiliser pour inspecter la requête dans le Dashboard afin de voir les paramètres reçus par Stripe ou le partager avec le service Support de Stripe lorsque vous rencontrez un problème.

Vous pouvez trouver les ID dans les logs de votre Dashboard, ou directement avec un code comme celui-ci :

customer = Stripe::Customer.create({ name: 'John Doe', })
puts customer.last_response.request_id

Définir des options de requête supplémentaires

Lors de l’envoi de requêtes API, vous pouvez définir des options de requête supplémentaires pour :

• Définir une version spécifique de l’API.
• Effectuer des requêtes concernant vos comptes connectés.
• Fournir des clés d’idempotence.

Gestion des erreurs

Chaque SDK côté serveur interprète les réponses d’erreur de l’API Stripe comme des types d’exception. Ainsi, vous n’avez pas besoin d’analyser vous-même l’état de la réponse. Utilisez les conventions de gestion des erreurs appropriées à chaque langage pour gérer ces erreurs.

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

En savoir plus sur la gestion des erreurs.

Undocumented params and fields

In some cases, you might encounter parameters on an API request or fields on an API response that aren’t available using the SDKs for strongly typed languages. Use the workarounds in this section to send undocumented parameters or access undocumented fields.

Envoyer des paramètres non documentés :

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

client.customers().create(params);

Accéder aux champs non documentés :

final Customer customer = client.customers().retrieve("cus_1234");
Boolean featureEnabled = customer.getRawJsonObject()
    .getAsJsonPrimitive("secret_feature_enabled")
    .getAsBoolean();

Code source

Le code source de chacun de nos SDK côté serveur est disponible sur GitHub :

StripeClient

La classe StripeClient sert de point d’entrée pour vous aider à découvrir des ressources et à envoyer des requêtes à l’API Stripe. Les avantages de l’utilisation de ce modèle par rapport à l’ancien qui utilisait une configuration globale sont les suivants :

• Vous pouvez utiliser simultanément plusieurs clients avec différentes options de configuration (telles que des clés API).
• Il permet de faciliter le mocking lors des tests, car StripeClient n’utilise pas de méthodes statiques.
• Aucun appel supplémentaire à l’API. Dans certaines langues, vous deviez appeler une récupération avant de procéder à une mise à jour ou à une suppression. Lorsque vous utilisez StripeClient, vous pouvez accéder à tous les endpoints d’API avec un seul appel de méthode.

Le SDK Node.js a toujours eu la classe Stripe qui suivait le même modèle. Pour les autres langues, le nouveau modèle a été ajouté dans les versions suivantes du SDK. Si vous comparez le code ciblant d’anciennes versions de ces bibliothèques avec des modèles plus anciens, les appels peuvent avoir une apparence différente.

Versions bêta

Stripe propose des fonctionnalités dans la phase de version bêta publique auxquelles vous pouvez accéder via les versions des SDK avec le suffixe -beta.X (par exemple, 15.2.0-beta.2). En savoir plus sur le canal de publication Public Preview.