Beantrage frühzeitigen Zugang

Gib deinen Vornamen und eine E-Mail-Adresse oder Telefonnummer an. Wir melden uns mit den Details zum Tajo-Zugang bei dir.

Auf dieser Seite

Install Links & Deep Links

Mit Install Links verteilst du deine Stripe App außerhalb des Marketplace, und Deep Links führen Nutzer:innen direkt zu einer bestimmten Ansicht innerhalb deiner installierten App. Beide sind für ein reibungsloses Onboarding und saubere Integrationsflows unverzichtbar.

Install Links

Install Links liefern eine direkte URL, über die Händler:innen deine App installieren können. Klickt jemand auf einen Install Link, übernimmt Stripe den Installationsflow und leitet danach zu der von dir angegebenen URI zurück.

Voraussetzungen

Bevor du Install Links verwendest, konfiguriere allowed_redirect_uris in deinem App-Manifest:

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

Format eines Install Links

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

Parameter	Erforderlich	Beschreibung
`client_id`	Ja	Deine App-ID (z. B. `com.tajo.brevo-integration`)
`redirect_uri`	Ja	Muss mit einer deiner `allowed_redirect_uris` übereinstimmen
`state`	Empfohlen	Zufällige Zeichenfolge zum CSRF-Schutz

Weiterleitungsparameter

Nach einer erfolgreichen Installation leitet Stripe die Person mit diesen Query-Parametern zu deiner redirect_uri weiter:

Parameter	Beschreibung
`user_id`	Die Stripe-Nutzer-ID des installierenden Kontos
`account_id`	Die Stripe-Konto-ID (z. B. `acct_xxxxx`)
`state`	Der `state`-Wert, den du übergeben hast (zur CSRF-Prüfung)
`install_signature`	HMAC-Signatur, mit der du die Echtheit der Installation prüfst

Beispiel für eine Weiterleitungs-URL:

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

CSRF-Schutz

Nutze immer den state-Parameter, um Cross-Site-Request-Forgery-Angriffe zu verhindern:

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');
};

Signaturprüfung

Prüfe die install_signature mit dem Signing Secret deiner App:

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

Nutze für den Signaturvergleich immer crypto.timingSafeEqual, um Timing-Angriffe zu verhindern. Verwende nie einen einfachen Zeichenkettenvergleich (===).

Signing Secret

Das Signing Secret deiner App findest du im Stripe Dashboard in den Einstellungen der App. Verwende es, um:

Install-Signaturen aus Weiterleitungs-Callbacks zu prüfen
Webhook-Payloads von Stripe zu validieren
Anfragen zwischen deinem Backend und Stripe zu authentifizieren

Bewahre das Signing Secret sicher auf:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Schreibe Signing Secrets nie fest in deinen Quellcode und checke sie nie in die Versionsverwaltung ein.

Deep Links

Deep Links führen Nutzer:innen direkt zu einer bestimmten Ansicht innerhalb deiner installierten Stripe App. Setze sie ein, um Personen aus externer Kommunikation (E-Mails, Benachrichtigungen, Support-Seiten) in den passenden App-Kontext zu bringen.

Format einer Deep-Link-URL

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

Komponente	Beschreibung	Beispiel
`MODE`	`live` oder `test`	`live`
`acct_ID`	Ziel-Stripe-Konto-ID	`acct_1234567890`
`PAGE`	Pfad der Dashboard-Seite	`customers/cus_xxxxx`
`APP_ID`	Die ID deiner App	`com.tajo.brevo-integration`
`TARGET`	`drawer` oder `modal`	`drawer`
`VIEWPORT_ID`	Der zu öffnende Viewport	`stripe.dashboard.customer.detail`

Target	Verhalten	Anwendungsfall
`drawer`	Öffnet die App im Seitenbereich (Drawer)	Standardinteraktion, Kontext neben der Seite
`modal`	Öffnet die App als bildschirmfüllendes Overlay	Fokussierte Abläufe, Onboarding, komplexe Formulare

Deep-Link-Beispiele

Kundendetailansicht im Drawer öffnen

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

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

Onboarding-Flow öffnen

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

Zahlungsdetailansicht im Testmodus öffnen

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

Deep Links programmatisch erzeugen

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',
});

Deep Links in der Kommunikation einsetzen

Deep Links sind besonders nützlich in:

E-Mail-Benachrichtigungen: „Brevo-Sync-Status für diese Kund:in ansehen”
Support-Antworten: „Hier klicken, um deine Integrationseinstellungen zu prüfen”
Onboarding-E-Mails: „Schließe deine Brevo-Einrichtung ab”
Fehlerwarnungen: „Sieh dir das Sync-Problem für Kund:in X an”

<!-- 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>

Install Links und Deep Links kombinieren

Für das beste Onboarding-Erlebnis kombinierst du Install Links mit Deep Links nach der Installation:

Eine Person klickt auf deiner Website oder in einer E-Mail auf einen Install Link
Sie installiert die App und wird zu deiner Callback-URL weitergeleitet
Dein Callback verarbeitet die Installation und leitet zu einem Deep Link weiter, der den Onboarding-Viewport öffnet

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

Teste Install Links und Deep Links immer sowohl im Live- als auch im Testmodus, damit sie in allen Umgebungen zuverlässig funktionieren.