# 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'
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_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`&nbsp;:

#### Créer

Créez un client nommé John Doe.

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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 "<<YOUR_SECRET_KEY>>:" \
  --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 "<<YOUR_SECRET_KEY>>:"
```

#### Récupérer

Récupérez le client correspondant à un ID donné.

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

#### Liste

Listez les 5&nbsp;clients les plus récemment créés.

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

#### Rechercher

Recherchez des clients nommés Jane Doe.

```curl
curl -G https://api.stripe.com/v1/customers/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --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)&nbsp;:

```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"
```

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&nbsp;:

#### 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: '',
})
```

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&nbsp;:

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

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

#### 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
```

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

```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&nbsp;:

#### 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
```

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&nbsp;:

- 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 "<<YOUR_SECRET_KEY>>:" \
    -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 "<<YOUR_SECRET_KEY>>:" \
    -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&nbsp;:

#### 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
```

## 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&nbsp;:

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

# 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
```

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

// 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);
```

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

// 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();
```

## Code source

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

| 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&nbsp;:

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