Richiedi l’accesso anticipato

Inserisci il tuo nome e un indirizzo email o un numero di telefono. Ti contatteremo con tutte le informazioni per accedere a Tajo.

In questa pagina

Link di installazione e deep link

I link di installazione ti permettono di distribuire la tua Stripe App fuori dal marketplace, mentre i deep link portano gli utenti direttamente a view specifiche all’interno dell’app installata. Entrambi sono essenziali per rendere fluidi i flussi di onboarding e integrazione.

Link di installazione

I link di installazione forniscono un URL diretto che i merchant possono usare per installare la tua app. Quando un utente clicca su un link di installazione, Stripe gestisce il flusso di installazione e poi reindirizza all’URI che hai indicato.

Prerequisiti

Prima di usare i link di installazione, configura allowed_redirect_uris nel manifest della tua app:

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

Formato del link di installazione

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

Parametro	Obbligatorio	Descrizione
`client_id`	Sì	L’ID della tua app (per esempio `com.tajo.brevo-integration`)
`redirect_uri`	Sì	Deve corrispondere a uno dei tuoi `allowed_redirect_uris`
`state`	Consigliato	Stringa casuale per la protezione CSRF

Parametri di reindirizzamento

Dopo un’installazione riuscita, Stripe reindirizza l’utente al tuo redirect_uri con questi parametri di query:

Parametro	Descrizione
`user_id`	L’ID utente Stripe dell’account che installa l’app
`account_id`	L’ID account Stripe (per esempio `acct_xxxxx`)
`state`	Il valore `state` che hai fornito (per la verifica CSRF)
`install_signature`	Firma HMAC per verificare che l’installazione sia legittima

Esempio di URL di reindirizzamento:

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

Protezione CSRF

Usa sempre il parametro state per prevenire gli attacchi di 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');
};

Verifica della firma

Verifica install_signature usando il signing secret della tua 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

Usa sempre crypto.timingSafeEqual per confrontare le firme, così eviti i timing attack. Non usare mai la semplice uguaglianza tra stringhe (===).

Signing secret

Il signing secret della tua app è disponibile nella Stripe Dashboard, nelle impostazioni dell’app. Usalo per:

Verificare le firme di installazione ricevute nelle callback di reindirizzamento
Validare i payload dei webhook inviati da Stripe
Autenticare le richieste tra il tuo backend e Stripe

Conserva il signing secret in modo sicuro:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Non inserire mai i signing secret direttamente nel codice sorgente e non committarli nel controllo di versione.

Deep link

I deep link portano gli utenti direttamente a una view specifica della tua Stripe App installata. Usali per indirizzare gli utenti dalle comunicazioni esterne (email, notifiche, pagine di assistenza) al contesto pertinente dell’app.

Formato dell’URL di un deep link

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

Componente	Descrizione	Esempio
`MODE`	`live` oppure `test`	`live`
`acct_ID`	ID dell’account Stripe di destinazione	`acct_1234567890`
`PAGE`	Percorso della pagina della Dashboard	`customers/cus_xxxxx`
`APP_ID`	L’ID della tua app	`com.tajo.brevo-integration`
`TARGET`	`drawer` oppure `modal`	`drawer`
`VIEWPORT_ID`	Il viewport da aprire	`stripe.dashboard.customer.detail`

Target	Comportamento	Caso d’uso
`drawer`	Apre l’app nel pannello laterale (drawer)	Interazione predefinita con l’app, contesto affiancato alla pagina
`modal`	Apre l’app in un overlay modale a schermo intero	Flussi che richiedono concentrazione, onboarding, moduli complessi

Esempi di deep link

Aprire la view di dettaglio del cliente nel drawer

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

Aprire le impostazioni in una modale

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

Aprire il flusso di onboarding

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

Aprire la view di dettaglio del pagamento in modalità test

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

Generare deep link in modo programmatico

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

Usare i deep link nelle comunicazioni

I deep link sono particolarmente utili in:

Notifiche email: “Vedi lo stato della sincronizzazione Brevo per questo cliente”
Risposte dell’assistenza: “Clicca qui per controllare le impostazioni della tua integrazione”
Email di onboarding: “Completa la configurazione di Brevo”
Avvisi di errore: “Controlla il problema di sincronizzazione del cliente 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>

Combinare link di installazione e deep link

Per la migliore esperienza di onboarding, combina i link di installazione con i deep link post-installazione:

L’utente clicca su un link di installazione dal tuo sito o da un’email
L’utente installa l’app e viene reindirizzato al tuo URL di callback
La tua callback elabora l’installazione e reindirizza l’utente a un deep link che apre il viewport di 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

Testa sempre i link di installazione e i deep link sia in modalità live sia in modalità test, per essere sicuro che funzionino correttamente in tutti gli ambienti.