Ajouter une logique côté serveur

Avec les applications Stripe, vous pouvez ajouter une logique côté serveur avec un back-end auto-hébergé. Avec un service back-end auto-hébergé, vous pouvez :

• Intégrez en toute sécurité les systèmes tiers qui nécessitent une intégration côté serveur.
• Inscrivez-vous aux événements de webhook de Stripe et synchronisez Stripe avec d’autres systèmes.
• Utilisez une logique d’application à long terme qui s’exécute lorsque l’utilisateur ferme le navigateur.
• Développez des applications qui offrent des fonctionnalités semblables à des tâches cron pour planifier des actions spécifiques.

Comment le back-end auto-hébergé est-il lié à l’application ?

Authentifier les utilisateurs entre votre interface utilisateur et le back-end de votre application

Pour authentifier un utilisateur à partir du Dashboard, le back-end a besoin d’une signature contenant la clé secrète partagée ainsi que le compte et l’ID de l’utilisateur actuellement connecté au Dashboard. Si votre utilisateur n’est pas autorisé à appeler l’API, Stripe renvoie une erreur d’autorisation.

Avant de commencer

1. Assurez-vous que votre service back-end peut envoyer et recevoir des requêtes HTTP. Si vous n’avez jamais créé de serveur API, essayez notre outil interactif pour la création d’endpoints de webhook.

2. Créez votre clé secrète partagée en chargeant votre application :

   Command Line

   stripe apps upload

   Ne vous inquiétez pas si vous n’avez pas terminé le développement de la version actuelle de votre application, le chargement ne mettra pas à jour votre application en mode production.

3. Obtenez la clé secrète de votre application pour vérifier la signature dans votre back-end :

   a. Accédez aux informations de votre application Stripe en sélectionnant votre application à partir de la section Apps.

   b. Sous l’ID de l’application, cliquez sur le menu de débordement (), puis sur Clé secrète de signature pour ouvrir la boîte de dialogue correspondante.

   c. Cliquez sur le Presse-papiers pour copier la clé secrète de votre application à partir de la boîte de dialogue Clé secrète de signature.

Envoyer une requête signée

Pour envoyer une requête signée au back-end de l’application :

1. Obtenez la signature actuelle à l’aide de la fonction asynchrone fetchStripeSignature.
2. Ajoutez la signature à l’en-tête Stripe-Signature.
3. Incluez les objets user_id et account_id dans la requête.
4. Sur le back-end de l’application, vérifiez que la requête comprenne la signature, la clé secrète de l’application, user_id et account_id.

Consultez un exemple d’envoi d’une requête signée avec des données supplémentaires.

Voici un exemple de requête d’une application Stripe avec l’en-tête Stripe-Signature :

import {fetchStripeSignature} from '@stripe/ui-extension-sdk/utils';

const App = ({ userContext, environment }: ExtensionContextValue) => {
  const makeRequestToMyBackend = async (endpoint, requestData) => {
    // By default the signature is signed with user id and account id.
    const signaturePayload = {
      user_id: userContext?.id,
      account_id: userContext?.account.id,
    };
    return fetch(`https://example.com/${endpoint}/`, {
      method: 'POST',
      headers: {
        'Stripe-Signature': await fetchStripeSignature(),
        'Content-Type': 'application/json',
      },
      // Include the account ID and user ID in the body to verify on backend.
      body: JSON.stringify({
        ...requestData,
        ...signaturePayload,
      }),
    });
  };
  ...
}

Exemple de back-end vérifiant la requête :

Veuillez noter que l’ordre et le nom des champs de la charge utile ont une incidence sur la vérification de la signature. user_id précède account_id, et l’objet résultant est le suivant : { user_id, account_id }account

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')(process.env.STRIPE_API_KEY);
const express = require('express');

// Find your app's secret in your app settings page in the Developers Dashboard.
const appSecret = 'absec_...';

// This example uses Express.
const app = require('express')();
app.use(express.json());

// Match the raw body to content type application/json.
app.post('/do_secret_stuff', (request, response) => {
  const sig = request.headers['stripe-signature'];
  // Retrieve user id and account id from the request body
  const payload = JSON.stringify({
    user_id: request.body['user_id'],
    account_id: request.body['account_id']
  });
  try {
    // Verify the payload and signature from the request with the app secret.
    stripe.webhooks.signature.verifyHeader(payload, sig, appSecret);
  } catch (error) {
    response.status(400).send(error.message);
  }
  // Handle the request by returning a response
  // to acknowledge receipt of the event.
  response.json({ success: true });
});

app.listen(3000, () => console.log('Running on port 3000'));

Envoyer une requête signée avec des données supplémentaires

Vous pouvez authentifier un utilisateur en envoyant une requête signée avec une charge utile (données supplémentaires). Lorsque vous appelez la fonction fetchStripeSignature avec une requête de données supplémentaires, vous créez une signature avec user_id, account_id et la charge utile supplémentaire que vous avez transmise à la fonction. Par défaut, Stripe Apps utilise user_id et account_id pour générer la chaîne de signature.

Exemple de génération d’une clé secrète avec une charge utile supplémentaire :

// A valid payload object has keys of type string
// and values of type string, number, or boolean.
const payload = {
  "transaction_id": 'ipi_1KRmFUFRwUQjTSJEjRnCCPyV',
  "amount": 100,
  "livemode": false,
};

fetch(`https://example.com/do_more_secret_stuff/`, {
  method: 'POST',
  headers: {
    'Stripe-Signature': await fetchStripeSignature(payload),
    'Content-Type': 'application/json',
  },
  // Append the account ID and user ID in the body to verify on backend.
  body: JSON.stringify({
    ...payload,
    user_id: 'usr_K6yd2CbXLO9A5G',
    account_id: 'acct_1JSkf6FRwUQjTSJE',
  }),
});

Exemple de back-end vérifiant la signature générée avec une charge utile supplémentaire :

// Match the raw body to content type application/json.
app.post('/do_more_secret_stuff', (request, response) => {
  try {
    // Verify the signature from the header and the request body that
    // contains the additional data, user ID, and account ID with the app secret.
    stripe.webhooks.signature.verifyHeader(request.body, sig, appSecret);
  } catch (error) {
    response.status(400).send(error.message);
  }
  // Handle the request by returning a response
  // to acknowledge receipt of the event.
  response.json({ success: true });
});

Vérifier les rôles d’utilisateur (facultatif)

Vous pouvez vérifier les rôles d’utilisateur affectés à un user_id donné en incluant la clé stripe_roles dans la charge utile. Fournissez-la avec userContext?.roles, qui renvoie une liste de RoleDefinitions. Si aucun rôle de la charge utile n’est affecté au paramètre user_id fourni, fetchStripeSignature renvoie une erreur de requête non valide (400).

// Provide this special key in the same way you'd
// provide any other key to the additional payload.
const payload = {
  "stripe_roles": userContext?.roles,
};

fetch(`https://example.com/do_more_secret_stuff/`, {
  method: 'POST',
  headers: {
    'Stripe-Signature': await fetchStripeSignature(payload),
    'Content-Type': 'application/json',
  },
  // Append the account ID and user ID in the body to verify on backend.
  body: JSON.stringify({
    ...payload,
    user_id: 'usr_K6yd2CbXLO9A5G',
    account_id: 'acct_1JSkf6FRwUQjTSJE',
  }),
});

Créer et faire expirer des clés secrètes

En cas de compromission de votre clé secrète, vous pouvez faire expirer la clé secrète actuelle de votre application immédiatement ou dans un délai de 24 heures pour mettre à jour la clé secrète de l’application dans votre back-end. Pendant cette période, deux clés secrètes sont actives pour l’endpoint, la clé compromise et la nouvelle clé générée. Stripe génère une signature par clé secrète jusqu’à l’expiration.

Pour créer et faire expirer une clé secrète d’application :

1. Accédez aux informations de votre application Stripe en sélectionnant cette dernière à partir de la section Applications.
2. Dans l’en-tête de la page, cliquez sur le menu de débordement (), puis sur Clé secrète de signature pour ouvrir la boîte de dialogue correspondante.
3. Cliquez sur Faire expirer la clé secrète dans la boîte de dialogue Clé secrète de signature pour ouvrir la boîte de dialogue Faire expirer la clé secrète.
4. Sélectionnez une durée d’expiration pour la clé secrète actuelle de votre application.
5. Cliquez sur Faire expirer la clé secrète.

Gérer le partage de ressources entre origines multiples (CORS)

Le CORS (partage de ressources entre origines multiples) est d’une aide importante pour sécuriser les applications face aux attaques « cross-site scripting » (XSS). Vous devez mettre en œuvre une approche spécifique pour gérer les en-têtes de requêtes d’origines multiples, car les extensions d’interface utilisateur d’une application Stripe sont nécessairement d’origines multiples et s’exécutent dans un iframe d’environnement de test.

Pour que votre extension d’interface utilisateur puisse récupérer les données de votre service back-end, vous devez configurer ce dernier pour qu’il effectue les actions suivantes :

• Autoriser les requêtes via la méthode Options.
• Pour autoriser les requêtes provenant d’origines null, définissez Access-Control-Allow-Origin sur *.

De nombreux frameworks back-end disposent de bibliothèques et proposent des conseils pour vous aider à gérer le CORS. Référez-vous à la documentation de votre framework pour des conseils plus précis.

Pour authentifier le fait qu’une requête provient de Stripe pour le compte d’un utilisateur ou d’un compte particulier, consultez la section Authentifier les utilisateurs entre votre interface utilisateur et votre back-end.

Utiliser les API de Stripe

Pour interagir avec Stripe, vous pouvez lancer et authentifier vos requêtes sur l’API Stripe.

Authentification des requêtes

Pour authentifier vos requêtes, utilisez la clé API de votre compte marchand existant pour interagir avec Stripe et spécifiez le stripeAccountId de l’utilisateur.

Pour les appels à l’API côté serveur, vous pouvez effectuer des requêtes en tant que comptes connectés à l’aide de l’en-tête spécial Stripe-Account et de l’identifiant de compte Stripe (qui commence par le préfixe acct_) de l’utilisateur de votre plateforme. Voici un exemple qui montre comment créer un PaymentIntent avec la clé API secrète de votre plateforme et l’identifiant du compte de votre utilisateur.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]"=card

L’approche d’en-tête Stripe-Account est implicite dans toute requête API qui inclut l’ID du compte Stripe dans l’URL. Voici un exemple qui montre comment récupérer un compte avec l’identifiant du compte de votre utilisateur dans l’URL.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

En outre, toutes les bibliothèques côté serveur de Stripe prennent en charge cette approche par requête, comme illustré dans l’exemple suivant :

Stripe.api_key = "{{PLATFORM_SECRET_KEY}}"
Stripe::Customer.create(
  {email: 'person@example.edu'},
  {stripe_account: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'}
)

# Fetching an account just needs the ID as a parameter
Stripe::Account.retrieve('{{CONNECTED_STRIPE_ACCOUNT_ID}}')

Appeler votre back-end auto-hébergé depuis l’extension d’interface utilisateur

Lorsque vous effectuez des requêtes depuis l’extension d’interface utilisateur vers le back-end, envoyez une signature avec votre requête pour valider la légitimité de vos requêtes. Depuis l’extension d’interface utilisateur, transmettez le stripeAccountId de l’utilisateur actif pour pouvoir effectuer des requêtes de back-end au nom de cet utilisateur.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2');
const express = require("express");
const app = express();

app.use(express.static("public"));
app.use(express.json());

app.post("/api/data", async (req, res) => {
  const { stripeAccountId } = req.body;

  const customer = await stripe.customers.create({
    description: 'My First Test Customer (created for API docs)',
  }, {
    stripeAccount: stripeAccountId,
  });

  res.send({
    data: []
  });
});

app.listen(3000, () => console.log("Node server listening on port 3000!"));

Appeler d’autres API

Depuis votre back-end auto-hébergé, vous pouvez appeler n’importe quelle API, qu’il s’agisse de la vôtre ou de celle d’un autre développeur ou d’une autre entreprise.

Pour en savoir plus sur le stockage des identifiants et des tokens dans votre application, consultez la page consacrée à ce sujet.

Si vous avez besoin de transmettre des informations utilisateur de Stripe vers un autre service, utilisez le stripeAccountId transmis depuis l’extension d’interface utilisateur.

const express = require('express');
const fetch = require('isomorphic-fetch');
const app = express();

app.use(express.static('public'));
app.use(express.json());

app.get('/api/time', async (req, res) => {
  fetch('http://worldclockapi.com/api/json/est/now')
    .then((response) => response.json())
    .then((data) => {
      res.send({
        data: data,
      });
    });
});

app.listen(3000, () => console.log('Node server listening on port 3000!'));

Vous pouvez également appeler une API tierce depuis l’extension d’interface utilisateur.

Recevoir des notifications d’événement concernant votre application

Écoutez les événements (comme les installations et désinstallations des utilisateurs) sur votre application Stripe en utilisant des webhooks entrants pour permettre à votre intégration de déclencher automatiquement des réactions sur votre back-end, telles que :

• La création de comptes utilisateur
• La mise à jour d’autorisations
• La désactivation d’un compte utilisateur et la suppression des données

Recevoir des événements

Vous pouvez recevoir des événements de la part de Stripe pour une application qui n’est accessible qu’à votre compte ou publiée sur l’App Marketplace :

Lorsqu’un marchand déclenche un événement, Stripe fournit l’objet Event suivant. Cet événement inclut la propriété account qui précise l’ID du compte du marchand à l’origine de l’événement :

{
  "id": "evt_wyHpZ2LZ5exgfe",
  "livemode": true,
  "object": "event",
  "type": "account.application.authorized",
  "account": "acct_wCaUi1YCzRBTBg",
  "pending_webhooks": 2,
  "created": 1349654313,
  "data": {...}
}

En utilisant l’attribut account, vous pouvez :

• Garder un œil sur le nombre de marchands qui installent et désinstallent votre application.
• Effectuer des appels à l’API au nom de vos utilisateurs à l’aide de Stripe Connect.

Événements pour Stripe Apps

Outre les types d’événements pris en charge par Stripe, les applications Stripe prennent en charge les événements suivants :

Event behavior depends on install mode

Your users can install apps in live mode, test mode, both modes, or a sandbox environment. Set webhooks according to the following guidelines:

• If the app is installed in a sandbox environment, events are only sent to the sandbox environment.
• If the app is installed in live mode only, live mode events are sent to the live mode endpoint.
• If the app is installed in test mode only, test mode events are sent to the test mode endpoint.
• If the app is installed in both modes, test mode events are sent to both the test mode and live mode endpoints, and live mode events are sent to the live mode endpoint.

Configure the Connect /webhook for live and test modes, then use the following snippet for both modes of the app. See the webhooks doc for a full endpoint example.

require 'sinatra'
require 'json'

post '/webhook' do
  event = JSON.parse(request.body.read)

  if event['livemode']
    puts "Handling live event: #{event}"
    # Handle live events
    handle_live_event(event)
  else
    puts "Handling test event: #{event}"
    # Handle test events
    handle_test_event(event)
  end

  status 200
  body 'Event received'
end

Troubleshooting

If you don’t receive expected events, review your configuration for the following common oversights:

• Make sure live mode webhooks use live mode keys and test mode webhooks use test mode keys.
• For live mode events, make sure the installing account is activated.
• Make sure that your app can handle both live mode & test mode events.
• Triggering test events doesn’t replicate live event behavior unless explicitly set up in the app configuration.

Tester des webhooks en local

Vous pouvez tester les webhooks en local pour :

• Une application qui n’est disponible que pour les utilisateurs de votre compte et qui écoute les événements sur votre propre compte
• Une application disponible sur le Stripe App Marketplace et qui écoute les événements sur les comptes qui ont installé votre application

Pour tester des webhooks en local :

1. Installez la CLI Stripe.

2. Authentifiez votre compte :

   Command Line

   stripe login

3. Ouvrez deux fenêtres de terminal :

   • Dans une fenêtre de terminal, configurez le transfert d’événements :

     Privée pour votre compte uniquement

     Publication sur l'App Marketplace

     Command Line

     stripe listen --forward-to localhost:{{PORT}}/webhook

   • Dans l’autre fenêtre de terminal, déclenchez des événements pour tester votre intégration des webhooks :

     Privée pour votre compte uniquement

     Publication sur l'App Marketplace

     Command Line

     stripe trigger {{EVENT_NAME}}

Pour plus d’informations, consultez notre documentation relative au test d’un point de terminaison de webhook.