Bed om tidlig adgang til Tajo

Indtast dit fornavn og en e-mailadresse eller et telefonnummer. Vi kontakter dig med oplysninger om adgang til Tajo.

På denne side

Installationslinks og dybe links

Installationslinks lader dig distribuere din Stripe App uden om marketplace, mens dybe links sender brugerne direkte til bestemte visninger i den app, de har installeret. Begge dele er afgørende for et glidende onboarding- og integrationsforløb.

Installationslinks

Installationslinks giver en direkte URL, som forhandlerne kan bruge til at installere din app. Når en bruger klikker på et installationslink, håndterer Stripe installationsforløbet og sender derefter brugeren tilbage til den URI, du har angivet.

Forudsætninger

Før du bruger installationslinks, skal du konfigurere allowed_redirect_uris i dit app-manifest:

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

Formatet for installationslinks

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

Parameter	Påkrævet	Beskrivelse
`client_id`	Ja	Dit app-ID (f.eks. `com.tajo.brevo-integration`)
`redirect_uri`	Ja	Skal matche en af dine `allowed_redirect_uris`
`state`	Anbefalet	Tilfældig streng til CSRF-beskyttelse

Redirect-parametre

Når installationen er gennemført, sender Stripe brugeren videre til din redirect_uri med disse forespørgselsparametre:

Parameter	Beskrivelse
`user_id`	Stripe-bruger-ID’et på den konto, der installerer
`account_id`	Stripe-konto-ID’et (f.eks. `acct_xxxxx`)
`state`	Den `state`-værdi, du angav (til CSRF-kontrol)
`install_signature`	HMAC-signatur, der bekræfter, at installationen er ægte

Eksempel på en redirect-URL:

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

CSRF-beskyttelse

Brug altid state-parameteren for at forhindre cross-site request forgery-angreb:

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

Verificering af signaturen

Verificer install_signature med din apps signeringsnøgle:

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

Brug altid crypto.timingSafeEqual til at sammenligne signaturer, så du undgår timingangreb. Brug aldrig simpel strengsammenligning (===).

Signeringsnøglen

Din apps signeringsnøgle finder du i Stripe Dashboard under din apps indstillinger. Brug den til at:

Verificere installationssignaturer fra redirect-callbacks
Validere webhook-payloads fra Stripe
Godkende forespørgsler mellem din backend og Stripe

Opbevar signeringsnøglen sikkert:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Skriv aldrig signeringsnøgler direkte i din kildekode, og commit dem aldrig til versionsstyring.

Dybe links

Dybe links sender brugerne direkte til en bestemt visning i den Stripe App, de har installeret. Brug dem til at føre brugerne fra ekstern kommunikation (e-mails, notifikationer, supportsider) til den relevante del af appen.

Formatet for dybe links

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

Komponent	Beskrivelse	Eksempel
`MODE`	`live` eller `test`	`live`
`acct_ID`	Stripe-konto-ID’et, du vil ramme	`acct_1234567890`
`PAGE`	Stien til siden i Dashboard	`customers/cus_xxxxx`
`APP_ID`	Din apps ID	`com.tajo.brevo-integration`
`TARGET`	`drawer` eller `modal`	`drawer`
`VIEWPORT_ID`	Den viewport, der skal åbnes	`stripe.dashboard.customer.detail`

Mål	Adfærd	Anvendelse
`drawer`	Åbner appen i sidepanelet (drawer)	Almindelig brug af appen, kontekst ved siden af siden
`modal`	Åbner appen som et overlay i fuld skærm	Fokuserede arbejdsgange, onboarding, komplekse formularer

Eksempler på dybe links

Åbn kundedetaljer i en 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

Åbn onboarding-forløbet

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

Åbn betalingsdetaljer i testtilstand

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

Generering af dybe links programmatisk

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

Brug af dybe links i kommunikation

Dybe links er især nyttige i:

E-mailnotifikationer: “Se Brevo-synkroniseringens status for denne kunde”
Supportsvar: “Klik her for at tjekke dine integrationsindstillinger”
Onboarding-e-mails: “Færdiggør din Brevo-opsætning”
Fejlalarmer: “Gennemgå synkroniseringsproblemet for kunde 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>

Kombination af installationslinks og dybe links

Du får det bedste onboarding-forløb ved at kombinere installationslinks med dybe links efter installationen:

Brugeren klikker på et installationslink fra dit website eller din e-mail
Brugeren installerer appen og sendes videre til din callback-URL
Din callback behandler installationen og sender brugeren videre til et dybt link, der åbner onboarding-viewporten

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 altid installationslinks og dybe links i både live- og testtilstand, så du er sikker på, at de virker i alle miljøer.