Utiliser des liens d'installationBêta

Définissez votre allowed_redirect_uris dans votre manifeste d’application. Ce sont les URL vers lesquelles les utilisateurs sont redirigés après avoir installé votre application. Vous devez spécifier toutes les URL de redirection dans les paramètres de votre application.

Après avoir défini allowed_redirect_uris, chargez une nouvelle version de votre application.

{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [],
  "app_backend": {},
  "ui_extension": {},
  "allowed_redirect_uris": [
    "https://example.com/callback/stripe"
  ]
}

Pour vérifier que le lien d’installation fonctionne avant de l’envoyer pour examen, vous pouvez utiliser le test externe en appliquant la procédure suivante :

1. Créez un test externe pour votre application en utilisant la version avec le allowed_redirect_uris définie dans le manifeste de l’application. Si un test existe déjà, vous pouvez mettre à jour la version de test vers celle souhaitée.
2. L’onglet Test externe présente un lien d’installation de test et affiche les redirections autorisées dans un tableau.
3. Lorsque vous êtes prêt à publier, assurez-vous de charger une nouvelle version dont les URL et les valeurs de test ont été remplacés par les valeurs que vous comptez utiliser en mode production.

Lorsque vous avez terminé les tests, vous pouvez le rendre disponible pour tous les utilisateurs en suivant les étapes ci-après :

1. Publiez une nouvelle version de votre application qui définit allowed_redirect_uris.
2. Cliquez sur l’onglet Paramètres. Vous pouvez copier le lien d’installation affiché. Il prend la forme suivante : https://marketplace.stripe.com/apps/install/link/{id}?redirect_uri=https://example.com.
3. Recommended Afin d’éviter toute attaque CSRF, vous pouvez ajouter et transmettre le paramètre recommandé state avec pour valeur un token unique. Nous inclurons la valeur state fournie lors de la redirection de l’utilisateur vers votre site. Ce dernier peut confirmer que le paramètre state n’a pas été modifié.
4. Une fois qu’un utilisateur a cliqué sur le lien d’installation, Stripe ouvre la page suivante sur laquelle il peut sélectionner un compte, consulter les informations relatives à l’application et procéder à l’installation.

Sélection du compte pour le lien d’installation

Une fois que l’utilisateur a installé votre application, il est redirigé vers l’URL définie dans le paramètre redirect_uri, qui correspond à une redirection définie dans allowed_redirect_uris dans le manifeste de votre application.

Installation réussie

Pour que les installations fonctionnent, l’URL doit inclure :

• La valeur user_id. L’ID de l’utilisateur Stripe qui a lancé l’installation.
• La valeur account_id. L’ID du compte Stripe qui a installé votre application.
• La valeur state, le cas échéant
• La valeur install_signature. Il s’agit d’un hachage des valeurs ci-dessus qui est généré à l’aide de la clé secrète de signature de votre application.
• Si l’application est installée en mode test, la valeur livemode=false est ajoutée à l’URL de redirection.

Exemple de redirection en mode production :

https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}

Exemple de redirection en mode test :

https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}&livemode=false

Échec de l’installation

Si l’utilisateur annule l’installation, il sera quand même redirigé vers votre site, mais cette fois l’URL comprendra une erreur :

https://example.com/callback/stripe?error=access_denied&error_description=The%20user%20denied%20your%20request

L’utilisateur est désormais connecté à votre application. Conservez le paramètre stripe_user_id dans votre base de données. Il s’agit de l’ID du compte Stripe de l’utilisateur. Vous utiliserez cette valeur pour l’authentification en tant que compte connecté en l’intégrant dans les requêtes dans l’en-tête Stripe-Account.

Vérifiez les installations d’applications avec install_signature Recommended

Il est important de vérifier que l’utilisateur de votre application est autorisé à installer l’application pour le compte indiqué dans l’URL de redirection. C’est pour cette raison qu’une install_signature est incluse. Cette signature est générée à partir de la clé secrète de signature de votre application et des paramètres user_id et account_id ayant effectué l’installation. La signature inclut également le paramètre state transmis, le cas échéant. La signature ne peut pas être répliquée sans accès à la clé secrète de signature, qui est uniquement disponible en interne pour Stripe et pour le back-end de votre application. Les personnes malveillantes ne peuvent donc pas reproduire le hachage s’ils tentent d’usurper l’URL de redirection. Vérifier la signature de l’application permet de garantir que le compte est associé à l’utilisateur de votre application.

Pour vérifier la signature, suivez ces étapes :

1. Si vous ne l’avez pas encore fait, créez la clé secrète de signature de votre application.
2. Configurez un back-end d’application pour vérifier la valeur install_signature.

Exemple de back-end vérifiant l’installation :

The order and naming of the payload fields matter when performing signature verification. The state precedes the user_id, which precedes the account_id. The resulting object should be { state, user_id, account_id }.

require 'stripe'
require 'sinatra'
require 'json'

Stripe.api_key = 'API_KEY'

get '/' do
  'Install Links verification example'
end

get '/verify' do
  user_id = params[:user_id]
  account_id = params[:account_id]
  state = params[:state]
  install_signature = params[:install_signature]

  payload = JSON.dump({
    state: state,
    user_id: user_id,
    account_id: account_id
  })

  begin
    Stripe::Webhook::Signature.verify_header(
      payload,
      install_signature,
      'STRIPE_APP_SECRET'
    )
  rescue Stripe::SignatureVerificationError => e
    return e.message, 400
  end

  { success: true }.to_json
end

set :port, 3000

Après vérification, vous pouvez effectuer des appels à l’API au nom du compte installé.

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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_4eC39HqLyjWDarjtT1zdp7dc
:"

Découvrez plus d’exemples de requêtes authentifiées ici.