Požiadajte o skorý prístup

Uveďte svoje krstné meno a e-mailovú adresu alebo telefónne číslo. Pošleme Vám podrobnosti o prístupe k platforme Tajo.

Na tejto stránke

Inštalačné a hĺbkové odkazy

Inštalačné odkazy Vám umožňujú distribuovať Vašu Stripe App mimo marketplace, zatiaľ čo hĺbkové odkazy privedú používateľa priamo na konkrétny pohľad vo Vašej nainštalovanej aplikácii. Oba typy sú kľúčové pre plynulý onboarding a integračné toky.

Inštalačné odkazy

Inštalačné odkazy poskytujú priamu URL, cez ktorú si obchodníci môžu nainštalovať Vašu aplikáciu. Keď používateľ klikne na inštalačný odkaz, Stripe zabezpečí priebeh inštalácie a potom ho presmeruje späť na Vami určenú URI.

Predpoklady

Skôr než začnete používať inštalačné odkazy, nastavte v manifeste aplikácie hodnotu allowed_redirect_uris:

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

Formát inštalačného odkazu

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

Parameter	Povinný	Popis
`client_id`	Áno	ID Vašej aplikácie (napr. `com.tajo.brevo-integration`)
`redirect_uri`	Áno	Musí zodpovedať jednej z hodnôt `allowed_redirect_uris`
`state`	Odporúčaný	Náhodný reťazec na ochranu proti CSRF

Parametre presmerovania

Po úspešnej inštalácii Stripe presmeruje používateľa na Vašu redirect_uri s týmito parametrami v dotaze:

Parameter	Popis
`user_id`	ID používateľa Stripe, ktorý aplikáciu inštaluje
`account_id`	ID účtu Stripe (napr. `acct_xxxxx`)
`state`	Hodnota `state`, ktorú ste odoslali (na overenie proti CSRF)
`install_signature`	HMAC podpis na overenie, že inštalácia je legitímna

Príklad URL presmerovania:

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

Ochrana proti CSRF

Vždy použite parameter state, aby ste zabránili útokom typu 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');
};

Overenie podpisu

Podpis install_signature overte pomocou podpisového tajomstva Vašej aplikácie:

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

Na porovnanie podpisov vždy používajte crypto.timingSafeEqual, aby ste predišli časovacím útokom. Nikdy nepoužívajte jednoduché porovnanie reťazcov (===).

Podpisové tajomstvo

Podpisové tajomstvo Vašej aplikácie nájdete v Stripe Dashboarde v nastaveniach aplikácie. Použite ho na:

Overenie podpisov inštalácie z návratových volaní presmerovania
Validáciu tiel webhookov od Stripe
Autentifikáciu požiadaviek medzi Vaším backendom a Stripe

Podpisové tajomstvo uchovávajte bezpečne:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Podpisové tajomstvá nikdy nezapisujte natvrdo do zdrojového kódu ani ich nepridávajte do systému na správu verzií.

Hĺbkové odkazy

Hĺbkové odkazy privedú používateľa priamo na konkrétny pohľad vo Vašej nainštalovanej Stripe App. Použite ich na to, aby ste používateľov z externej komunikácie (e-maily, notifikácie, stránky podpory) doviedli do príslušného kontextu aplikácie.

Formát URL hĺbkového odkazu

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

Časť	Popis	Príklad
`MODE`	`live` alebo `test`	`live`
`acct_ID`	ID cieľového účtu Stripe	`acct_1234567890`
`PAGE`	Cesta k stránke dashboardu	`customers/cus_xxxxx`
`APP_ID`	ID Vašej aplikácie	`com.tajo.brevo-integration`
`TARGET`	`drawer` alebo `modal`	`drawer`
`VIEWPORT_ID`	Pohľad, ktorý sa má otvoriť	`stripe.dashboard.customer.detail`

Cieľ	Správanie	Použitie
`drawer`	Otvorí aplikáciu v bočnom paneli (drawer)	Bežná práca s aplikáciou, kontext vedľa stránky
`modal`	Otvorí aplikáciu v celoobrazovkovom modálnom okne	Sústredené postupy, onboarding, zložité formuláre

Príklady hĺbkových odkazov

Otvorenie detailu zákazníka v bočnom paneli

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

Otvorenie nastavení v modálnom okne

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

Otvorenie onboardingového toku

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

Otvorenie detailu platby v testovacom režime

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

Programové generovanie hĺbkových odkazov

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

Používanie hĺbkových odkazov v komunikácii

Hĺbkové odkazy sú obzvlášť užitočné v týchto prípadoch:

E-mailové notifikácie: „Zobraziť stav synchronizácie s Brevo pre tohto zákazníka”
Odpovede podpory: „Kliknutím sem skontrolujete nastavenia svojej integrácie”
Onboardingové e-maily: „Dokončite nastavenie Brevo”
Upozornenia na chyby: „Skontrolujte problém so synchronizáciou pre zákazníka 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>

Kombinovanie inštalačných a hĺbkových odkazov

Pre najlepší onboarding skombinujte inštalačné odkazy s hĺbkovými odkazmi po inštalácii:

Používateľ klikne na inštalačný odkaz na Vašom webe alebo v e-maile
Používateľ nainštaluje aplikáciu a systém ho presmeruje na Vašu návratovú URL
Vaše návratové volanie spracuje inštaláciu a presmeruje používateľa na hĺbkový odkaz, ktorý otvorí onboardingový pohľad

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

Inštalačné aj hĺbkové odkazy vždy otestujte v ostrom aj testovacom režime, aby ste mali istotu, že fungujú správne vo všetkých prostrediach.