# Migrer vers la méthode de réponse directe aux webhooks

Découvrez comment migrer les autorisations Issuing en temps réel à partir d’appels à l’API obsolètes vers la méthode de réponse directe aux webhooks.

Répondez directement à un [webhook issuing_authorization.request](https://docs.stripe.com/issuing/controls/real-time-authorizations.md) avec une décision d’autorisation en temps réel au lieu de faire un appel à l’API aux endpoints obsolètes [approve](https://docs.stripe.com/api/issuing/authorizations/approve.md) et [decline](https://docs.stripe.com/api/issuing/authorizations/decline.md) pendant le traitement webhook. Répondre directement à l’événement webhook simplifie les autorisations en temps réel et supprime un appel à l’API supplémentaire, qui pourrait réduire votre taux d’autorisation en raison des expirations.

Si vous développez une nouvelle intégration, [utilisez des réponses webhook directes](https://docs.stripe.com/issuing/controls/real-time-authorizations.md). Si vous avez une intégration existante qui utilise les appels à l’API `/approve` et `/decline`, migrez-la vers des réponses webhook directes.

> Ce guide ne s’applique que si vous utilisez les endpoints `/approve` et `/decline` pour les autorisations en temps réel.

## Flux d’appels à l’ancienne API

Auparavant, vous deviez effectuer un appel à l’API à `/approve` ou `/decline` pour prendre une décision concernant une demande d’autorisation entrante avant de répondre au webhook `issuing_authorization.request`.

(See full diagram at https://docs.stripe.com/issuing/controls/real-time-authorizations/direct-webhook-migration)

```text
[Titulaire de carte] -- Tentative d’achat --> [Stripe]
[Stripe] -- POST issuing_authorization.request --> [Utilisateur]
[Utilisateur] -- Prendre une décision --> [Utilisateur]
[Utilisateur] -- POST /approve --> [Stripe]
[Stripe] -- 200 Réponse à /approve --> [Utilisateur]
[Utilisateur] -- Clôturer la demande de webhook --> [Utilisateur]
[Utilisateur] -- 200 Réponse à issuing_authorization.request --> [Stripe]
[Stripe] -- Achat approuvé --> [Titulaire de carte]
```

## Nouveau flux de réponse direct pour les webhooks

Vous pouvez désormais répondre directement au webhook `issuing_authorization.request` avec une décision dans le corps de la réponse, sans avoir besoin d’effectuer un appel à l’API distinct. Une fois la décision prise, un événement webhook `issuing_authorization.created` ou `issuing_authorization.updated` est toujours envoyé.

Pour en savoir plus sur cette API, consultez la [documentation relative aux autorisations en temps réel](https://docs.stripe.com/issuing/controls/real-time-authorizations.md) et créez une intégration avec [notre guide interactif](https://docs.stripe.com/issuing/controls/real-time-authorizations/quickstart.md).

(See full diagram at https://docs.stripe.com/issuing/controls/real-time-authorizations/direct-webhook-migration)

```text
[Titulaire de carte] -- Tentative d’achat --> [Stripe]
[Stripe] -- POST issuing_authorization.request --> [Utilisateur]
[Utilisateur] -- Prendre une décision --> [Utilisateur]
[Utilisateur] -- 200 Réponse à l’ensemble d’en-tête issuing_authorization.request {approved: true} et Stripe-Version --> [Stripe]
[Stripe] -- Achat approuvé --> [Titulaire de carte]
```

Vous devez répondre avec un code d’état HTTP `200`, un en-tête `Stripe-Version` défini sur une version spécifique de l’API et une valeur booléenne `approved` dans le corps JSON. Le corps JSON doit correspondre à la [version spécifiée de l’API](https://docs.stripe.com/api/versioning.md).

Pour les autorisations à montant contrôlable, les [approbations partielles](https://docs.stripe.com/issuing/purchases/authorizations.md?issuing-authorization-type=incremental_authorization#handling-other-authorizations) incluent facultativement `amount`.

### Modifications dans l’API d’autorisation du webhook direct

Pour les [autorisations](https://docs.stripe.com/api/issuing/authorizations/object.md) de réponse directe aux webhooks, nous avons effectué plusieurs ajouts :

- Ajout de la valeur `webhook_error` à [request_history.reason](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history-reason). Cette valeur est présente si la réponse du webhook échoue en raison d’erreurs de validation.
- Nouveau champ `request_history.reason_message`, qui inclut un message d’erreur détaillé si la valeur de `request_history.reason` est `webhook_error`.

## Migrer vers la réponse directe

Vous pouvez essayer la réponse directe du webhook dans les environnements de test. Au titre de bonne pratique, nous vous recommandons de passer progressivement de l’ancien appel à l’API à une réponse directe au webhook.

Si vous appelez une méthode API et incluez le corps de la réponse directe du webhook, la décision de la méthode API est prioritaire.

Voici un exemple de ce à quoi peut ressembler une migration vers le webhook direct dans Ruby. Pour les autres langues, consultez [notre guide interactif](https://docs.stripe.com/issuing/controls/real-time-authorizations/quickstart.md).

```ruby
# User's existing API call webhook handling code, using Sinatra.
# In this example, the synchronous webhook and normal webhook share an endpoint.
client = Stripe::StripeClient.new(ENV.fetch('STRIPE_API_KEY'))
post '/webhook' do
  payload = request.body.read

  if event['type'] == 'issuing_authorization.request'
    auth = event['data']['object']
    # Approve with legacy API call.
    client.v1.issuing.authorizations.approve(auth["id"])
    status 200
  elsif event['type'] == 'issuing_authorization.created'
    auth = event['data']['object']
    # If approved, will print "webhook_approved"
    puts "#{auth["request_history"][-1]["reason"]}"
    status 200
  end
end
```

Après avoir effectué des tests dans un *environnement de test* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes), transférez progressivement le trafic vers la réponse directe du webhook.

```ruby
# User's API call and direct response webhook handling code, using Sinatra.
# In this example, the synchronous webhook and normal webhook share an endpoint.
client = Stripe::StripeClient.new(ENV.fetch('STRIPE_API_KEY'))
post '/webhook' do
  payload = request.body.read

  if event['type'] == 'issuing_authorization.request'
    auth = event['data']['object']

    # Gradually shift traffic over from API approval to direct webhook response.
    if should_use_direct_webhook_response?(auth["id"])
      # Direct webhook response.

      body({
        # Required field, containing decision.
        "approved" => true,
      }.to_json)

      header({
        # Required in header. Versions can be found in https://stripe.com/docs/api/versioning
        "Stripe-Version" => "2023-08-16"
      })

      # Must respond with a 200.
      status 200
    else
      # Legacy API call. Plan to remove this after traffic is completely shifted.
      client.v1.issuing.authorizations.approve(auth["id"])
      status 200
    end
  elsif event['type'] == 'issuing_authorization.created'
    auth = event['data']['object']

    # If approved, will print "webhook_approved"
    puts "#{auth["request_history"][-1]["reason"]}"

    # Handle new reason value and field
    if auth["request_history"][-1]["reason"] == "webhook_error"
      puts "Direct webhook response decision failed: #{auth["request_history"][-1]["reason_message"]}"
    end
    status 200
  end
end
```