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

  cURL

  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

  cURL

  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 d’API spécifique.
• 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.

Fonctionnalités des versions bêta privées

Stripe lance régulièrement des fonctionnalités de version bêta privée qui introduisent de nouvelles propriétés ou de nouveaux paramètres qui ne sont pas immédiatement rendus publics. Les SDK à typage dynamique (PHP, Node, Ruby, Python) les prennent automatiquement en charge. Pour les SDK fortement typés (Java, .NET, Go), utilisez le code ci-dessous, sauf s’ils sont pris en charge dans une version bêta.

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 :

Modèles de service et de relation client

Pour certains SDK, nous avons introduit un modèle de service et de relation client qui modifie votre mode d’exécution des opérations. Ce nouveau modèle basé sur les services facilite la simulation sans méthodes statiques et permet à plusieurs instances client de fonctionner simultanément avec une configuration distincte.

Si vous comparez du code ciblant des versions antérieures de ces bibliothèques avec des modèles basés sur les ressources, les appels peuvent être différents.

Versions bêta

Nous proposons des SDK en phase bêta, identifiables à la présence du suffixe beta ou b dans le nom de fichier, par exemple 5.1.0-beta.3 ou 5.1.0b3. Ils vous donnent accès aux produits et fonctionnalités en cours de développement, et vous permettent de nous faire part de vos commentaires avant leur disponibilité générale.

Accédez aux versions bêta du SDK via le fichier readme.md du référentiel GitHub correspondant.