Vraag vroegtijdige toegang aan

Vul je voornaam en een e-mailadres of telefoonnummer in. We nemen daarna contact met je op en leggen uit hoe je toegang krijgt tot Tajo.

Op deze pagina

Installatielinks en deeplinks

Met installatielinks verspreid je je Stripe App buiten de marketplace om, terwijl deeplinks gebruikers rechtstreeks naar een specifieke weergave binnen je geïnstalleerde app brengen. Allebei zijn ze onmisbaar voor soepele onboarding en integratietrajecten.

Installatielinks

Een installatielink is een directe URL waarmee handelaren je app kunnen installeren. Wanneer een gebruiker op een installatielink klikt, verzorgt Stripe het installatieproces en stuurt daarna terug naar de URI die jij hebt opgegeven.

Vereisten

Configureer allowed_redirect_uris in het manifest van je app voordat je installatielinks gebruikt:

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

Opbouw van een installatielink

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

Parameter	Verplicht	Beschrijving
`client_id`	Ja	De ID van je app (bijvoorbeeld `com.tajo.brevo-integration`)
`redirect_uri`	Ja	Moet overeenkomen met een van je `allowed_redirect_uris`
`state`	Aanbevolen	Willekeurige tekenreeks voor CSRF-bescherming

Redirectparameters

Na een geslaagde installatie stuurt Stripe de gebruiker naar je redirect_uri met deze queryparameters:

Parameter	Beschrijving
`user_id`	De Stripe-gebruikers-ID van het installerende account
`account_id`	De Stripe-account-ID (bijvoorbeeld `acct_xxxxx`)
`state`	De `state`-waarde die je hebt meegegeven (voor CSRF-verificatie)
`install_signature`	HMAC-handtekening om te bevestigen dat de installatie legitiem is

Voorbeeld van een redirect-URL:

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

CSRF-bescherming

Gebruik altijd de state-parameter om cross-site request forgery-aanvallen te voorkomen:

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

Handtekeningverificatie

Verifieer de install_signature met het signing secret van je 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

Gebruik altijd crypto.timingSafeEqual om handtekeningen te vergelijken, zo voorkom je timingaanvallen. Gebruik nooit een gewone tekenreeksvergelijking (===).

Signing secret

Het signing secret van je app vind je in het Stripe-dashboard bij de instellingen van je app. Je gebruikt het om:

Installatiehandtekeningen uit redirect-callbacks te verifiëren
Webhookpayloads van Stripe te valideren
Verzoeken tussen je backend en Stripe te authenticeren

Bewaar het signing secret veilig:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Zet signing secrets nooit hard in je broncode en commit ze nooit naar versiebeheer.

Deeplinks

Deeplinks brengen gebruikers rechtstreeks naar een specifieke weergave binnen je geïnstalleerde Stripe App. Gebruik ze om gebruikers vanuit externe communicatie (e-mails, meldingen, supportpagina’s) naar de juiste context in de app te leiden.

Opbouw van een deeplink-URL

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

Onderdeel	Beschrijving	Voorbeeld
`MODE`	`live` of `test`	`live`
`acct_ID`	De Stripe-account-ID van de bestemming	`acct_1234567890`
`PAGE`	Het pad van de dashboardpagina	`customers/cus_xxxxx`
`APP_ID`	De ID van je app	`com.tajo.brevo-integration`
`TARGET`	`drawer` of `modal`	`drawer`
`VIEWPORT_ID`	De viewport die geopend wordt	`stripe.dashboard.customer.detail`

Target	Gedrag	Toepassing
`drawer`	Opent de app in het zijpaneel (drawer)	Standaardinteractie met de app, context naast de pagina
`modal`	Opent de app in een schermvullende modal	Gerichte workflows, onboarding, complexe formulieren

Voorbeelden van deeplinks

Klantdetails openen in de drawer

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

Het onboardingtraject openen

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

Betalingsdetails openen in testmodus

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

Deeplinks programmatisch genereren

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

Deeplinks gebruiken in je communicatie

Deeplinks zijn vooral handig in:

E-mailmeldingen: “Bekijk de status van de Brevo-synchronisatie voor deze klant”
Supportantwoorden: “Klik hier om je integratie-instellingen te controleren”
Onboarding-e-mails: “Rond je Brevo-installatie af”
Foutmeldingen: “Bekijk het synchronisatieprobleem voor klant 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>

Installatielinks en deeplinks combineren

Combineer installatielinks met deeplinks na de installatie voor de beste onboarding-ervaring:

De gebruiker klikt op een installatielink op je website of in een e-mail
De gebruiker installeert de app en wordt doorgestuurd naar je callback-URL
Je callback verwerkt de installatie en stuurt de gebruiker door naar een deeplink die de onboardingviewport opent

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

Test installatielinks en deeplinks altijd in zowel de live- als de testmodus, zodat je zeker weet dat ze in elke omgeving goed werken.