Connecter Polar et lier ses commandes aux visites

01Connecter Polar

1. 1

   Créer un jeton d’accès dans Polar

   Tally ne fait que lire vos commandes ; il n’a jamais besoin de déplacer de l’argent. Dans Polar, ouvrez Settings, Access Tokens, créez un jeton d’accès d’organisation, et donnez-lui uniquement ces portées :

   Autorisation	Accès	Pourquoi
   Organizations	organizations:read	Le nom de l’organisation, pour savoir laquelle est connectée.
   Orders	orders:read	Chaque paiement : son montant, ses taxes, ses métadonnées et l’e-mail du client (haché immédiatement, jamais stocké).
   Refunds	refunds:read	Remboursements.
   Disputes	disputes:read	Rétrofacturations : les litiges que vous avez perdus.
   Webhooks	webhooks:write	Tally ajoute son propre endpoint de webhook, pour que les paiements arrivent en quelques secondes.

   Un jeton sandbox fonctionne aussi : Tally essaie la sandbox de Polar quand la production ne connaît pas le jeton.

2. 2

   Coller le jeton d’accès

   Sur la page Integrations de votre site (ou à l’étape Payments quand vous ajoutez un site), ouvrez Polar et renseignez :

   • Access token : il commence par polar_oat_. Tally le stocke chiffré et ne l’affiche plus jamais.

   Cliquez ensuite sur Connect Polar.

3. 3

   Tally vérifie l’accès et importe l’année écoulée

   Il nomme toute portée manquante, ajoute son propre endpoint de webhook pour que les nouvelles commandes arrivent au moment où elles ont lieu, et importe les 365 derniers jours, remboursements et litiges perdus compris.

02Transmettre l’identifiant du visiteur dans les métadonnées

Là où votre serveur crée le paiement, lisez le cookie _tally_vid et transmettez-le en tally_visitor_id dans metadata : Polar le copie sur la commande et sur l’abonnement, et les renouvellements suivent donc. Sur un lien de paiement, ajoutez l’identifiant du visiteur en reference_id, que Polar conserve dans les métadonnées du paiement.

// Express with cookie-parser, where you create the Polar checkout.
app.post('/checkout', async (req, res) => {
  const visitorId = req.cookies['_tally_vid'];
  const response = await fetch('https://api.polar.sh/v1/checkouts/', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.POLAR_ACCESS_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      products: ['your-product-id'],
      metadata: visitorId ? { 'tally_visitor_id': visitorId } : {},
      success_url: 'https://example.com/thanks?checkout_id={CHECKOUT_ID}',
    }),
  });
  const checkout = await response.json();
  res.redirect(303, checkout.url);
});

// On pages with Polar checkout links: add the visitor id as reference_id. Polar's embed
// marks its links with data-polar-checkout; use your own selector for plain links.
const visitorId = (document.cookie.match(/(?:^|; )_tally_vid=([\w-]+)/) || [])[1];
for (const link of document.querySelectorAll('a[data-polar-checkout]')) {
  const url = new URL(link.href);
  if (visitorId && !url.searchParams.has('reference_id')) {
    url.searchParams.set('reference_id', visitorId);
    link.href = url.href;
  }
}

03Sur un site sans cookie

Sans cookie, il n’y a pas d’identifiant à transmettre, alors identifiez l’acheteur par l’e-mail qu’il utilise pour payer : objectifs et identify.

04Vérifier que ça marche

05Ce qui n’est pas lu