Aperçu des API v2

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

• API v1: L’espace de noms /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

Tout SDK côté serveur prend en charge les API de l’espace de noms { % code %}{ % $constant.values.v2.terms.namespace-v2 %}{ % /code %}.

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.

Pour accéder aux API dans l’/v2 espace de noms en utilisant la CLI Stripe, utilisez la commande stripe v2. Par exemple, pour lister tous les Comptes v2, vous pouvez utiliser Stripe v2 core accounts list.

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/event_destinations \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-09-30.acacia" \

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
EventDestination eventDestination = stripe.v2().core().eventDestinations().retrieve("ed_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/event_destinations

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

Défilement de liste

API dans l’espace de noms /v2 (par exemple, GET /v2/core/event_destinations) 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 estnull.

Vous pouvez utiliser ces URL pour effectuer des requêtes sans utiliser nos SDK. À l’inverse, lorsque vous utilisez nos SDK, vous n’avez pas besoin d’utiliser ces URL, car les SDK gèrent automatiquement la pagination automatique.

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

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

EventDestinationListParams params = EventDestinationListParams.builder().build();

for (EventDestination eventDestination : stripe.v2().core().eventDestinations().list(params).autoPagingIterable()) {
  // process event destination object
}

Utilisation des paramètres de requête dans les requêtes API

Utilisez des filtres sur les endpoints de la liste pour limiter les résultats. Utilisez les paramètres include sur les endpoints GET pris en charge pour retourner des champs supplémentaires dans la réponse. Les filtres et les paramètres include permettent de transmettre un tableau de valeurs. Lorsque vous effectuez des requêtes API directes (sans utiliser de SDK côté serveur ou la CLI), vous devez toujours spécifier l’index de la valeur du tableau en notation avec des crochets, même si vous ne transmettez qu’une seule valeur.

Par exemple, pour lister tous Accounts où la applied_configuration est définie sur merchant, transférez ce qui suit :

curl -G https://api.stripe.com/v2/core/accounts?applied_configurations[0]=merchant
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-12-15.clover" \

Pour lister tous les comptes où la configuration est définie sur merchant oucustomer, utilisez la syntaxe suivante :

curl -G https://api.stripe.com/v2/core/accounts?applied_configurations[0]=merchant&applied_configurations[1]=customer
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-12-15.clover" \

Vous pouvez utiliser la même technique pour les paramètres include. Par exemple, pour inclure plusieurs champs dans une réponse, utilisez la syntaxe suivante :

curl -G https://api.stripe.com/v2/core/accounts/:id?include[0]=requirements&include[1]=defaults&include[2]=identity
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-12-15.clover" \

Dans certains cas, un tableau est imbriqué dans un paramètre de requête. Par exemple, pour obtenir une liste de méthodes de virement, vous pouvez fournir un tableau de valeurs à filtrer sur le champ imbriqué usage_status[payments] :

curl -G https://api.stripe.com/v2/money_management/payout_methods?usage_status[payments][0]=eligible&usage_status[payments][1]=invalid
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-12-15.preview" \

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 a échoué (ou a échoué partiellement), l’API réexécute les requêtes ayant échoué et renvoie la nouvelle réponse.
• Lors des rares occasions où une relance idempotente ne peut plus fonctionner, l’API renvoie un message d’erreur explicatif.

Une requête est considérée comme une réémission idempotente d’une autre requête si les éléments suivants sont tous vrais :

• 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
• Elles surviennent à moins de 30 jours d’intervalle

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.
• Une requête est considérée comme une réémission idempotente d’une autre requête car :
  • 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 apparaissent en moins de 30 jours consécutifs.
• 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 de l’API, même s’il s’agissait 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>

Limites

• Vous pouvez toujours tester les endpoints /v2 dans un environnement de test. Vous pouvez également tester certaines API v2, telles que Facturation établie sur l’utilisation et Destinations événementielles, en mode test.
• Actuellement, Stripe ne génère que des événements légers utilisant /v2 des endpoints et des ressources.
• Vous ne pouvez voir que les logs de requêtes générés par API v2 dansÉtabli, pas dans le Dashboard des développeurs.