ドキュメントPolar

03 · 売上

Polar を接続し、注文を訪問に紐づける

Tally は、必要なスコープだけを持つトークンで、Polar の注文、返金、敗れた異議申し立てを読み取ります。

01Polar を接続する

  1. Polar でアクセストークンを作成する

    Tally が行うのは注文の読み取りだけで、お金を動かす必要はありません。Polar で Settings, Access Tokens を開き、組織アクセストークンを作成して、次のスコープだけを付けます。

    権限アクセス用途
    Organizationsorganizations:read組織名(どの組織が接続されているかを確認するため)。
    Ordersorders:readすべての支払い:金額、税額、メタデータ、顧客のメールアドレス(すぐにハッシュ化し、保存はしません)。
    Refundsrefunds:read返金。
    Disputesdisputes:readチャージバック:負けた異議申し立て。
    Webhookswebhooks:writeTally が専用の Webhook エンドポイントを追加するので、支払いは数秒で届きます。

    サンドボックスのトークンも使えます。本番環境がトークンを認識しない場合、Tally は Polar のサンドボックスで試します。

  2. アクセストークンを貼り付ける

    サイトの Integrations ページ(またはサイト追加時の Payments の手順)で Polar を開き、次を入力します。

    • Access token:polar_oat_ で始まります。Tally は暗号化して保管し、二度と表示しません。

    続いて Connect Polar を押します。

  3. Tally が確認し、過去 1 年分を取り込む

    トークンに足りないスコープがあればその名前を示し、新しい注文を発生と同時に受け取れるよう専用の Webhook エンドポイントを追加して、返金と敗れた異議申し立てを含む過去 365 日分を取り込みます。

02メタデータで訪問者 ID を渡す

サーバーでチェックアウトを作成する箇所で _tally_vid Cookie を読み取り、metadata に tally_visitor_id として渡します。Polar がこれを注文とサブスクリプションにコピーするため、更新分にも引き継がれます。チェックアウトリンクでは訪問者 ID を reference_id として付けます。Polar はこれをチェックアウトのメタデータに保持します。

コードを表示

// 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;
  }
}

03Cookie なしのサイトの場合

Cookie がないと渡す ID もないため、支払いに使うメールアドレスで購入者を identify します:ゴールと identify。

04うまくいったか確認する

05読み取らないもの

足りない情報や、実際の画面と違う点はありませんか? どのページかを添えて support@tallybyoutpost.com までお知らせください。