Demandez un accès anticipé

Indiquez votre prénom ainsi qu’une adresse e-mail ou un numéro de téléphone. Nous vous recontacterons pour vous communiquer les modalités d’accès à Tajo.

Sur cette page

Liens d’installation et liens profonds

Les liens d’installation vous permettent de distribuer votre Stripe App en dehors de la marketplace, tandis que les liens profonds amènent les utilisateurs directement vers une vue précise de votre application installée. Les deux sont indispensables à des parcours d’onboarding et d’intégration fluides.

Liens d’installation

Un lien d’installation fournit une URL directe que les marchands peuvent utiliser pour installer votre application. Lorsqu’un utilisateur clique sur un lien d’installation, Stripe prend en charge le parcours d’installation, puis le renvoie vers l’URI que vous avez indiquée.

Prérequis

Avant d’utiliser des liens d’installation, configurez allowed_redirect_uris dans le manifest de votre application :

{
  "id": "com.tajo.brevo-integration",
  "allowed_redirect_uris": [
    "https://tajo.io/stripe/callback",
    "https://tajo.io/stripe/oauth/complete"
  ]
}

Format du lien d’installation

https://marketplace.stripe.com/oauth/v2/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&state=STATE_VALUE

Paramètre	Requis	Description
`client_id`	Oui	L’ID de votre application (par exemple `com.tajo.brevo-integration`)
`redirect_uri`	Oui	Doit correspondre à l’une de vos `allowed_redirect_uris`
`state`	Recommandé	Chaîne aléatoire servant à la protection CSRF

Paramètres de redirection

Après une installation réussie, Stripe redirige l’utilisateur vers votre redirect_uri avec ces paramètres de requête :

Paramètre	Description
`user_id`	L’ID utilisateur Stripe du compte qui installe l’application
`account_id`	L’ID de compte Stripe (par exemple `acct_xxxxx`)
`state`	La valeur `state` que vous avez fournie, pour la vérification CSRF
`install_signature`	Signature HMAC permettant de vérifier que l’installation est légitime

Exemple d’URL de redirection :

https://tajo.io/stripe/callback
  ?user_id=usr_xxxxx
  &account_id=acct_xxxxx
  &state=abc123random
  &install_signature=sig_xxxxx

Protection CSRF

Utilisez toujours le paramètre state pour prévenir les attaques de type cross-site request forgery :

import crypto from 'crypto';

// Generate a random state value and store it in the session
const generateInstallLink = (req, res) => {
  const state = crypto.randomBytes(32).toString('hex');

  // Store state in session for later verification
  req.session.stripeInstallState = state;

  const installUrl = new URL('https://marketplace.stripe.com/oauth/v2/authorize');
  installUrl.searchParams.set('client_id', 'com.tajo.brevo-integration');
  installUrl.searchParams.set('redirect_uri', 'https://tajo.io/stripe/callback');
  installUrl.searchParams.set('state', state);

  res.redirect(installUrl.toString());
};

// Handle the redirect callback
const handleInstallCallback = async (req, res) => {
  const { state, user_id, account_id, install_signature } = req.query;

  // Verify state matches what we stored
  if (state !== req.session.stripeInstallState) {
    return res.status(403).json({ error: 'Invalid state parameter' });
  }

  // Clear the stored state
  delete req.session.stripeInstallState;

  // Verify the install signature
  if (!verifyInstallSignature(install_signature, account_id)) {
    return res.status(403).json({ error: 'Invalid install signature' });
  }

  // Process the successful installation
  await processInstallation(user_id, account_id);

  res.redirect('/dashboard/stripe-connected');
};

Vérification de la signature

Vérifiez la valeur install_signature à l’aide du secret de signature de votre application :

import crypto from 'crypto';

const verifyInstallSignature = (signature, accountId) => {
  const signingSecret = process.env.STRIPE_APP_SIGNING_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(accountId)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
};

Caution

Utilisez toujours crypto.timingSafeEqual pour comparer les signatures, afin de prévenir les attaques temporelles. N’utilisez jamais une simple égalité de chaînes (===).

Secret de signature

Le secret de signature de votre application est disponible dans le Dashboard Stripe, dans les paramètres de l’application. Utilisez-le pour :

Vérifier les signatures d’installation issues des callbacks de redirection
Valider les charges utiles des webhooks envoyés par Stripe
Authentifier les requêtes échangées entre votre backend et Stripe

Stockez le secret de signature de manière sécurisée :

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

N’inscrivez jamais un secret de signature en dur dans votre code source et ne le versionnez jamais.

Liens profonds

Les liens profonds amènent les utilisateurs directement vers une vue précise de votre Stripe App installée. Utilisez-les pour conduire les utilisateurs depuis vos communications externes (e-mails, notifications, pages d’assistance) vers le contexte applicatif pertinent.

Format d’URL des liens profonds

https://dashboard.stripe.com/MODE/acct_ID/PAGE?apps[APP_ID][TARGET]=VIEWPORT_ID

Composant	Description	Exemple
`MODE`	`live` ou `test`	`live`
`acct_ID`	ID du compte Stripe cible	`acct_1234567890`
`PAGE`	Chemin de la page du Dashboard	`customers/cus_xxxxx`
`APP_ID`	L’ID de votre application	`com.tajo.brevo-integration`
`TARGET`	`drawer` ou `modal`	`drawer`
`VIEWPORT_ID`	Le viewport à ouvrir	`stripe.dashboard.customer.detail`

Cible	Comportement	Cas d’usage
`drawer`	Ouvre l’application dans le panneau latéral (drawer)	Interaction par défaut, contexte affiché à côté de la page
`modal`	Ouvre l’application dans une modale en plein écran	Parcours ciblés, onboarding, formulaires complexes

Exemples de liens profonds

Ouvrir la vue de détail client dans le drawer

https://dashboard.stripe.com/live/acct_xxxxx/customers/cus_xxxxx
  ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.customer.detail

Ouvrir les paramètres dans une modale

https://dashboard.stripe.com/live/acct_xxxxx/settings
  ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.settings

Ouvrir le parcours d’onboarding

https://dashboard.stripe.com/live/acct_xxxxx/dashboard
  ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.onboarding

Ouvrir la vue de détail du paiement en mode test

https://dashboard.stripe.com/test/acct_xxxxx/payments/pi_xxxxx
  ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.payment.detail

Générer des liens profonds par programmation

const generateDeepLink = ({
  accountId,
  mode = 'live',
  page,
  appId = 'com.tajo.brevo-integration',
  target = 'drawer',
  viewport,
}) => {
  const baseUrl = `https://dashboard.stripe.com/${mode}/${accountId}/${page}`;
  const params = new URLSearchParams();
  params.set(`apps[${appId}][${target}]`, viewport);

  return `${baseUrl}?${params.toString()}`;
};

// Generate a link to view a customer's Brevo profile
const customerLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'customers/cus_xxxxx',
  viewport: 'stripe.dashboard.customer.detail',
});

// Generate a link to app settings
const settingsLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'settings',
  viewport: 'stripe.dashboard.settings',
  target: 'modal',
});

Utiliser les liens profonds dans vos communications

Les liens profonds sont particulièrement utiles dans :

Les notifications par e-mail : « Voir le statut de synchronisation Brevo de ce client »
Les réponses du support : « Cliquez ici pour vérifier les paramètres de votre intégration »
Les e-mails d’onboarding : « Terminez votre configuration Brevo »
Les alertes d’erreur : « Consultez le problème de synchronisation du client X »

<!-- Example in an email template -->
<a href="https://dashboard.stripe.com/live/acct_xxxxx/customers/cus_xxxxx?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.customer.detail">
  View Brevo Profile in Stripe
</a>

Combiner liens d’installation et liens profonds

Pour offrir le meilleur onboarding possible, associez les liens d’installation à des liens profonds après installation :

L’utilisateur clique sur un lien d’installation depuis votre site web ou un e-mail
L’utilisateur installe l’application et est redirigé vers votre URL de callback
Votre callback traite l’installation, puis redirige l’utilisateur vers un lien profond qui ouvre le viewport d’onboarding

const handleInstallCallback = async (req, res) => {
  const { account_id, install_signature, state } = req.query;

  // Verify state and signature
  // ... (verification code)

  // Process installation
  await processInstallation(account_id);

  // Redirect to the app's onboarding view via deep link
  const onboardingLink = generateDeepLink({
    accountId: account_id,
    page: 'dashboard',
    viewport: 'stripe.dashboard.onboarding',
    target: 'modal',
  });

  res.redirect(onboardingLink);
};

Tip

Testez systématiquement vos liens d’installation et vos liens profonds en mode live comme en mode test, afin de vérifier qu’ils fonctionnent correctement dans tous les environnements.