Erken erişim talep edin

Adınızı ve e-posta adresinizi veya telefon numaranızı paylaşın. Tajo erişim ayrıntıları için sizinle iletişime geçeceğiz.

Bu sayfada

Kurulum bağlantıları ve derin bağlantılar

Kurulum bağlantıları, Stripe App’inizi pazar yeri dışında dağıtmanızı sağlar; derin bağlantılar ise kullanıcıları kurulu uygulamanızdaki belirli görünümlere doğrudan yönlendirir. Her ikisi de sorunsuz bir kullanıcı başlangıcı ve entegrasyon akışı için gereklidir.

Kurulum bağlantıları

Kurulum bağlantıları, satıcıların uygulamanızı kurmak için kullanabileceği doğrudan bir URL sunar. Bir kullanıcı kurulum bağlantısına tıkladığında Stripe kurulum akışını yürütür ve ardından belirttiğiniz URI’ye geri yönlendirir.

Ön koşullar

Kurulum bağlantılarını kullanmadan önce uygulama manifest dosyanızda allowed_redirect_uris değerini yapılandırın:

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

Kurulum bağlantısı biçimi

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

Parametre	Zorunlu	Açıklama
`client_id`	Evet	Uygulama kimliğiniz (örneğin `com.tajo.brevo-integration`)
`redirect_uri`	Evet	`allowed_redirect_uris` değerlerinizden biriyle eşleşmelidir
`state`	Önerilir	CSRF koruması için rastgele dizi

Yönlendirme parametreleri

Kurulum başarıyla tamamlandıktan sonra Stripe, kullanıcıyı şu sorgu parametreleriyle redirect_uri adresinize yönlendirir:

Parametre	Açıklama
`user_id`	Kurulumu yapan hesabın Stripe kullanıcı kimliği
`account_id`	Stripe hesap kimliği (örneğin `acct_xxxxx`)
`state`	Sağladığınız `state` değeri (CSRF doğrulaması için)
`install_signature`	Kurulumun meşru olduğunu doğrulayan HMAC imzası

Örnek yönlendirme URL’si:

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

CSRF koruması

Siteler arası istek sahteciliği saldırılarını önlemek için her zaman state parametresini kullanın:

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

İmza doğrulama

install_signature değerini uygulamanızın imzalama gizli anahtarıyla doğrulayın:

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

Zamanlama saldırılarını önlemek için imza karşılaştırmasında her zaman crypto.timingSafeEqual kullanın. Basit dize eşitliğini (===) asla kullanmayın.

İmzalama gizli anahtarı

Uygulamanızın imzalama gizli anahtarı, Stripe Dashboard’da uygulamanızın ayarları altında bulunur. Şunlar için kullanın:

Yönlendirme geri çağrılarından gelen kurulum imzalarını doğrulamak
Stripe’tan gelen webhook yüklerini doğrulamak
Arka ucunuz ile Stripe arasındaki isteklerin kimliğini doğrulamak

İmzalama gizli anahtarını güvenli biçimde saklayın:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

İmzalama gizli anahtarlarını asla kaynak kodunuza sabit olarak yazmayın ve sürüm kontrolüne göndermeyin.

Derin bağlantılar

Derin bağlantılar, kullanıcıları kurulu Stripe App’inizdeki belirli bir görünüme doğrudan yönlendirir. Kullanıcıları dış iletişim kanallarından (e-postalar, bildirimler, destek sayfaları) ilgili uygulama bağlamına yönlendirmek için kullanın.

Derin bağlantı URL biçimi

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

Bileşen	Açıklama	Örnek
`MODE`	`live` veya `test`	`live`
`acct_ID`	Hedef Stripe hesap kimliği	`acct_1234567890`
`PAGE`	Dashboard sayfa yolu	`customers/cus_xxxxx`
`APP_ID`	Uygulamanızın kimliği	`com.tajo.brevo-integration`
`TARGET`	`drawer` veya `modal`	`drawer`
`VIEWPORT_ID`	Açılacak görünüm alanı	`stripe.dashboard.customer.detail`

Hedef	Davranış	Kullanım durumu
`drawer`	Uygulamayı yan panelde (çekmece) açar	Varsayılan uygulama etkileşimi, sayfanın yanında bağlam
`modal`	Uygulamayı tam ekran modal katmanında açar	Odaklanmış iş akışları, kullanıcı başlangıcı, karmaşık formlar

Derin bağlantı örnekleri

Müşteri detay görünümünü çekmecede açma

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

Kullanıcı başlangıç akışını açma

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

Ödeme detay görünümünü test modunda açma

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

Derin bağlantıları programatik olarak oluşturma

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

Derin bağlantıları iletişimlerde kullanma

Derin bağlantılar özellikle şu durumlarda işe yarar:

E-posta bildirimleri: “Bu müşteri için Brevo senkronizasyon durumunu görüntüleyin”
Destek yanıtları: “Entegrasyon ayarlarınızı kontrol etmek için buraya tıklayın”
Başlangıç e-postaları: “Brevo kurulumunuzu tamamlayın”
Hata uyarıları: “X müşterisindeki senkronizasyon sorununu inceleyin”

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

Kurulum bağlantılarını derin bağlantılarla birleştirme

En iyi kullanıcı başlangıç deneyimi için kurulum bağlantılarını kurulum sonrası derin bağlantılarla birleştirin:

Kullanıcı, web sitenizdeki veya e-postanızdaki bir kurulum bağlantısına tıklar
Kullanıcı uygulamayı kurar ve geri çağrı URL’nize yönlendirilir
Geri çağrınız kurulumu işler ve kullanıcıyı, başlangıç görünüm alanını açan bir derin bağlantıya yönlendirir

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

Tüm ortamlarda doğru çalıştıklarından emin olmak için kurulum bağlantılarını ve derin bağlantıları hem canlı hem de test modunda mutlaka test edin.