Présentation de l'API v2

L’API Stripe fournit deux espaces de noms qui contiennent plusieurs ensembles de endpoints :

• API v1 : l’ /v1 inclut la plupart des API Stripe existantes.
• API v2 : l’espace de noms /v2 comprend des endpoints qui utilisent des modèles de conception /v2.

Différences clés entre les espaces de noms v1 et v2

SDK prenant en charge l’API v2

Tous les SDK côté serveur (à l’exception de Golang) prennent en charge les API dans l’espace de noms /v2suivant :

If you use Golang, access APIs in the /v2 namespace with the custom requests feature.

Utiliser l’API v2 avec la CLI Stripe

Utilisez stripe trigger et stripe listen pour tester la gestion des événements de votre intégration. Vous ne pouvez pas accéder aux API dans l’espace de noms /v2 en utilisant l’interface de ligne de commande Stripe.

Gestion des versions du SDK, de la CLI et de l’API

Les SDK et la CLI Stripe incluent automatiquement une version d’API pour chaque requête. Une fois que vous avez mis à jour la version de votre SDK ou de la CLI, Stripe met à jour simultanément la version de l’API de vos requêtes et réponses.

Inclure la version Stripe sans SDK ou CLI

Toutes les requêtes API envoyées à l’espace de noms de l’API /v2 doivent inclure l’en-tête Stripe-Version pour spécifier la version sous-jacente de l’API.

Voici un exemple de requête curl utilisant la version 2024-09-30.acacia de l’API :

curl -G https://api.stripe.com/v2/core/events \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-09-30.acacia" \
  -d object_id=fa_123

Utiliser les API des espaces de noms v1 et v2 dans la même intégration

Vous pouvez utiliser toutes les combinaisons d’API dans l’espace de noms /v1 ou /v2 dans la même intégration.

import com.stripe.StripeClient;

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

// Call a v2 API
Event event = stripe.v2().core().events().retrieve("evt_123");

// Call a v1 API
Customer customer = stripe.customers().retrieve("cus_123");

Si vous n’utilisez pas un SDK officiel ni la CLI, renseignez toujours l’espace de noms dans l’URL de vos appels à l’API. Par exemple :

# Call a v2 API
curl https://api.stripe.com/v2/core/events?object_id=mtr_123

# Call a v1 API
curl https://api.stripe.com/v1/charges -d amount=2000 -d currency=usd

Défilement de liste

Les API de l’espace de noms /v2(par exemple, GET /v2/core/events) contiennent une interface de pagination différente de celles de l’espace de noms /v1.

• La propriété previous_page_url renvoie une URL permettant de récupérer la page précédente de la liste. S’il n’y a pas de page précédente, la valeur est null.
• La propriété next_page_url envoie une URL permettant de récupérer la page suivante de la liste. S’il n’y a pas de page suivante, la valeur est null.

Vous ne pouvez pas modifier les filtres de liste après la première requête.

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

EventListParams params =
  EventListParams.builder()
    .setObjectId("mtr_123")
    .build();

for (Event event : stripe.v2().core().events().list(params).autoPagingIterable()) {
  // process event object
}

Idempotence

Les API de l’espace de noms /v2 permettent une meilleure prise en charge des comportements idempotents en empêchant les effets indésirables involontaires lors de l’exécution répétée de requêtes sur la même clé d’idempotence. Lorsque l’API reçoit deux requêtes ayant la même clé d’idempotence :

• Si la première requête a abouti, l’API ne procède pas à de nouvelles modifications et renvoie une nouvelle réponse.
• Si la première requête échoue (ou échoue partiellement), l’API relance les requêtes en échec et renvoie la nouvelle réponse.
• Dans les rares occasions où une relance idempotente ne peut plus fonctionner, l’API renvoie un message d’erreur explicatif.

Deux requêtes sont considérées comme idempotentes si les conditions suivantes sont remplies :

• Elles utilisent la même clé d’idempotence pour la même API
• Elles se produisent au sein du même compte ou environnement de test
• Survenir à 30 jours d’intervalle maximum

Pour spécifier une clé d’idempotence, utilisez l’en-tête Idempotency-Key et renseignez une valeur unique pour représenter l’opération (nous vous recommandons d’utiliser un UUID). Si aucune clé n’est renseignée, Stripe génère automatiquement un UUID.

Toutes les requêtes API v2 POST et DELETE acceptent les clés d’idempotence et ont un comportement idempotent. Les requêtes GET étant idempotentes par nature, l’envoi d’une clé d’idempotence n’a aucun effet.

Différences d’idempotence entre API v1 et API v2

Les idempotences API v1 et API v2 présentent quelques différences majeures :

• API v1 prend uniquement en charge les relances idempotentes pour les requêtes POST. API v2 prend en charge toutes les requêtes POST et DELETE.
• Deux requêtes soient considérées comme idempotentes si :
  • API v1 elles utilisent la même clé d’idempotence et se produisent à moins de 24 heures d’intervalle.
  • API v2 elles utilisent la même clé d’idempotence, la même API, se produisent au sein du même compte ou environnement de test et sont créées dans les 30 jours qui suivent.
• Lorsque vous fournissez la même clé d’idempotence pour deux requêtes :
  • API v1 renvoie toujours la réponse précédemment enregistrée de la première requête API, même s’il s’agit d’une erreur.
  • API v2 tente de relancer les requêtes en échec sans engendrer d’effet indésirable (toute modification superflue ou tout comportement observable résultant d’un appel à l’API) et de fournir une réponse actualisée.

Requêtes idempotentes

À l’aide du SDK, fournissez une clé d’idempotence avec la propriété idempotencyKey dans les requêtes à l’API.

Par exemple, pour effectuer une requête API avec une clé d’idempotence spécifique :

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

String idempotencyKey = "unique-idempotency-key";
Example result = stripe.v2().examples().create(
        ExampleCreateParams.builder()
          .setName("My example")
          .build(),

        RequestOptions.builder()
          .setIdempotencyKey(idempotencyKey)
          .build());

Si vous n’utilisez pas de SDK ni la CLI, les requêtes peuvent inclure l’en-tête Idempotency-Key :

curl https://api.stripe.com/v2/examples \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  -H "Idempotency-Key: unique-idempotency-key" \
  -d <JSON request body>

Limitations

• Le mode test ne prend pas en charge /v2, cependant, vous pouvez utiliser un environnement de test pour effectuer des tests dans cet espace de noms.
• Les clés limitées ne prennent actuellement pas en charge API v2. Pour appeler API v2, utilisez une clé secrète.
• Le SDK Go ne prend actuellement pas en charge /v2 directement, cependant vous pouvez effectuer des requêtes personnalisées aux API /v2.
• Actuellement, Stripe ne génère que des événements légers utilisant /v2 des endpoints et des ressources.
• L’interface de ligne de commande prend en charge les commandes trigger et listen pour les événements légers /v2, cependant elle ne prend pas en charge la création de ressources /v2.
• Le Dashboard du développeur et Workbench n’affichent pas les /v2 événements légers dans l’onglet Événements généraux, cependant, nous affichons les /v2 événements légers pour chaque destination d’événement dans l’onglet Envoi d’événements.
• Vous ne pouvez voir les logs des requêtes générés par l’API v2 que dans Workbench, pas dans le Dashboard des développeurs.