どの決済サービスの決済も記録する

01決済を記録できるキーを作成する

サイトの Setup ページの API keys で、キーに名前を付けて Record payments にチェックを入れます。キーが表示されるのは 1 回だけで、一覧では Records payments の印が付きます。チェックのないキーは読み取り専用で、ここでは 403 で拒否されます。

02決済を 1 件ずつ送信する

サーバーが決済を受け取ったら、決済サービスにかかわらず、キーを Authorization: Bearer … とし、JSON の本文を付けて POST https://tallybyoutpost.com/api/v1/payments に送信します。購入者のリクエストの _tally_vid Cookie から読み取った訪問者 ID も一緒に送ります。

// Express with cookie-parser, where your server records a payment it took.
app.post('/paid', async (req, res) => {
  await fetch('https://tallybyoutpost.com/api/v1/payments', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.TALLY_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 29.99,
      currency: 'USD',
      transaction_id: 'order_1042',
      tally_visitor_id: req.cookies['_tally_vid'],
      email: 'buyer@example.com',
    }),
  });
  res.sendStatus(204);
});

curl https://tallybyoutpost.com/api/v1/payments \
  -H "Authorization: Bearer $TALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 29.99, "currency": "USD", "transaction_id": "order_1042", "tally_visitor_id": "the _tally_vid cookie"}'

# Where your server records a payment it took (requests, Flask).
import os
import requests

requests.post(
    "https://tallybyoutpost.com/api/v1/payments",
    headers={"Authorization": "Bearer " + os.environ["TALLY_API_KEY"]},
    json={
        "amount": 29.99,
        "currency": "USD",
        "transaction_id": "order_1042",
        "tally_visitor_id": request.cookies.get("_tally_vid"),
        "email": "buyer@example.com",
    },
    timeout=10,
)

03フィールド

amount数値必須

支払われた金額。通貨の基本単位（29.99）で、税込みです。小数の文字列も使えます。0 より大きい値にします。amount が 0 の場合は無料トライアルとみなし、何も記録しません。

currency文字列必須

3 文字の ISO 4217 コード：USD、EUR、JPY。

transaction_id文字列必須

あなたのシステムでの決済の ID（最大 200 文字、数値も可）。サイト内で一意で、同じ ID を再送信すると 2 件目の決済ではなく重複として扱います。

tally_visitor_id文字列

_tally_vid Cookie の値。決済を訪問に結びつけます。datafast_visitor_id と visitor_id も同じように読み取ります。

email文字列

メールアドレスで照合するための、購入者のメールアドレス。受信時にハッシュ化し、保持するのはハッシュだけです。customer_email も使えます。

name文字列

DataFast の本文がそのまま使えるように受け付けますが、保存はしません。customer_name も同様です。

customer_id文字列

あなたのシステムでの購入者の ID。subscription_id のない更新は、その顧客の初回決済を引き継ぎます。

subscription_id文字列

サブスクリプションの決済をまとめ、各更新が初回決済を引き継ぐようにします。

renewal真偽値

この決済がサブスクリプションの更新であることを示します（どのサブスクリプションかは subscription_id、なければ customer_id で示します）。帰属先は初回決済と同じになります。

refunded真偽値

transaction_id で指定した決済に対する、amount の金額の返金であることを示します。一部返金も可能です。

refund_id文字列

1 件の決済に複数の一部返金がある場合の、あなたのシステムでの返金の ID。これがないと、同じ決済に対する 2 回目の返金は重複として扱われます。

is_free_trial真偽値

支払いのないトライアル。何も記録せず、応答は 200 です。

tax数値デフォルト 0

amount のうち税額にあたる部分。収益は税を除いて数えます。

timestamp文字列デフォルトは現在時刻

支払われた日時。2026-11-10T12:00:00Z のように、タイムゾーン付きの ISO 8601 形式で指定します。未来の日時は数分先までです。

本文のそのほかの項目は無視します。

04応答の内容

決済を記録したとき、またはすでに記録済みだったときは、JSON とともに 200 を返します。

{"message": "Payment recorded. It's linked to its visit within a few seconds.", "transaction_id": "order_1042", "duplicate": false}

それ以外は、API のほかの部分と同じくエラーになります：{"error": {"code", "message"}}。message はそのまま表示できる一文です。

05更新と返金

更新では、サブスクリプション（または顧客）を指定して renewal を設定します。帰属先はサブスクリプションの初回決済と同じになります。

curl https://tallybyoutpost.com/api/v1/payments \
  -H "Authorization: Bearer $TALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 29.99, "currency": "USD", "transaction_id": "inv_2207", "subscription_id": "sub_88", "renewal": true}'

返金では refunded を設定し、取り消す対象の決済を transaction_id で指定して、返金額を渡します。1 件の決済に対する一部返金には、それぞれ固有の refund_id を付けてください。

curl https://tallybyoutpost.com/api/v1/payments \
  -H "Authorization: Bearer $TALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10, "currency": "USD", "transaction_id": "order_1042", "refunded": true, "refund_id": "rf_1"}'

06各決済の紐づけ方

応答の後、ほかの決済サービスと同じルールで紐づけます。訪問者 ID は確度「高」で（チェックアウトのメタデータとして）、メールアドレスは確度「中」で（購入者のブラウザがそのアドレスで identify を呼び出していた場合）紐づき、更新と返金は元の決済に従います。紐づけの仕組み。

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