# Introduction aux SDK côté serveur Découvrez comment installer et utiliser les SDK Stripe 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é](https://docs.stripe.com/sdks/community.md) 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. #### 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' ``` Une fois l’installation terminée, vous devez initialiser Stripe : #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' ``` ## 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` : #### Créer Créez un client nommé John Doe. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d "name=John Doe" ``` #### Modifier Récupérez le client correspondant à un ID donné. ```curl curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "<>:" \ --data-urlencode "email=jdoe@example.com" ``` #### Supprimer Supprimer le client correspondant à un ID donné. ```curl curl -X DELETE https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "<>:" ``` #### Récupérer Récupérez le client correspondant à un ID donné. ```curl curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "<>:" ``` #### Liste Listez les 5 clients les plus récemment créés. ```curl curl -G https://api.stripe.com/v1/customers \ -u "<>:" \ -d limit=5 ``` #### Rechercher Recherchez des clients nommés Jane Doe. ```curl curl -G https://api.stripe.com/v1/customers/search \ -u "<>:" \ --data-urlencode "query=name:'Jane 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 curl https://api.stripe.com/v1/customers \ -u "<>:" \ -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 : #### Ruby ```ruby 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](https://docs.stripe.com/metadata.md). ## 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 : ```json { "id": "pi_001", "object": "payment_intent", "amount": 1099, "currency": "usd", /* ... */ } ``` Utilisez une variable pour accéder aux propriétés de cet objet : #### Ruby ```ruby 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 : ```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" } ``` Utilisez une boucle sur la `data` matrice pour accéder aux propriétés de chaque objet : #### Ruby ```ruby paymentIntentList = Stripe::PaymentIntent.list({ limit: 3 }) for pi in paymentIntentList.data do puts pi.amount end ``` Vous pouvez également utiliser la [pagination automatique](https://docs.stripe.com/pagination.md#auto-pagination) 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é. ```curl curl -G https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` - Récupérez une session Checkout et incluez la propriété `line_items`. ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{SESSION_ID}} \ -u "<>:" \ -d "expand[]=line_items" ``` En savoir plus sur le [développement des réponses](https://docs.stripe.com/expand.md). ## 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](https://dashboard.stripe.com/test/workbench/logs) de votre Dashboard, ou directement avec un code comme celui-ci : #### Ruby ```ruby 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 d’API spécifique](https://docs.stripe.com/sdks/set-version.md). - [Effectuer des requêtes concernant vos comptes connectés](https://docs.stripe.com/connect/authentication.md). - [Fournir des clés d’idempotence](https://docs.stripe.com/api/idempotent_requests.md). ## 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. #### Ruby ```ruby 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](https://docs.stripe.com/error-handling.md). ## Paramètres et champs non documentés Dans certains cas, vous pouvez rencontrer des paramètres sur une requête API ou des champs sur une réponse API qui ne sont pas disponibles dans les SDK. Cela peut arriver lorsqu’ils sont non renseignés ou en version bêta et que vous n’utilisez pas de SDK en version bêta. Utilisez les instructions suivantes pour envoyer ces paramètres ou accéder à ces champs. ### Envoyer des paramètres non renseignés Dans l’exemple suivant, vous créez un `Customer` avec un paramètre booléen non renseigné. L’exemple de code utilise `secret_feature_enabled`, que les SDK n’exposent pas. #### Java ```java CustomerCreateParams params = CustomerCreateParams.builder() .setEmail("jenny.rosen@example.com") .putExtraParam("secret_feature_enabled", "true") .build(); client.customers().create(params); ``` ### Accéder aux champs non renseignés Dans l’exemple suivant, vous lisez un champ booléen non documenté sur l’objet `Customer`. L’exemple de code utilise`secret_feature_enabled`, que les SDK n’exposent pas. #### Java ```java 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 : | Langue | Répertoire | | ---------- | ---------------------------------------------------------- | | **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 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. | Guides de migration | Version StripeClient | | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | [Guide de migration vers Stripe-php](https://github.com/stripe/stripe-php/wiki/Migration-to-StripeClient-and-services-in-7.33.0) | 7.33.0 | | [Guide de migration vers Stripe-python](https://github.com/stripe/stripe-python/wiki/Migration-guide-for-v8-\(StripeClient\)) | 8.0.0 | | [Guide de migration vers Stripe-java](https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v23#stripeclient) | 23.0.0 | | [Guide de migration Stripe-ruby](https://github.com/stripe/stripe-ruby/wiki/Migration-guide-for-v13) | 13.0.0 | | [Guide de migration Stripe-dotnet](https://github.com/stripe/stripe-dotnet/blob/master/CHANGELOG.md#stripeclient) | 46.0.0 | | [Guide de migration Stripe-go](https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client#migrating-from-global-configuration) | 82.1.0 | ## Versions préliminaires publiques et privées Stripe propose des fonctionnalités en [version bêta publique et privée](https://docs.stripe.com/release-phases.md) que vous pouvez accéder via des versions des SDKs avec les [suffixes `beta` ou `b` ](https://docs.stripe.com/sdks/versioning.md#public-preview-release-channel)et [`alpha` ou `a`respectivement](https://docs.stripe.com/sdks/versioning.md#private-preview-release-channel).