Paddle を接続する
読み取り専用の Paddle API キーを貼り付けて、ソフトウェアや SaaS の売上、返金、税額を製品別・国別に取り込みます。
Paddle は、アプリストアの外で販売するソフトウェア（デスクトップアプリ、Web アプリ、SaaS プラン、ライセンス）の merchant of record です。OAuth ではなく、読み取り専用の API キー 1 つで接続します。Paddle のダッシュボードでキーを作成し、Revenue Sensor に貼り付けて、同期する Paddle の製品を選ぶだけです。キーは暗号化して保存され、当社のサーバーから外に出ることはありません。Paddle のログイン情報を使うこともありません。
始める前に
- 売上を追跡したい販売者アカウントの Paddle ダッシュボードへのアクセス権と、Developer tools で API キーを作成できる権限。
- 本番（live）アカウントとサンドボックスのどちらを使うかを決めておくこと。Paddle はそれぞれに別のキーを発行し、どちらを読み取るかはキーで決まります。ほかに選ぶものはありません。
読み取り専用の API キーを作成する
- 1
Developer tools を開く
Paddle のダッシュボードで Developer tools → Authentication に移動し、新しい API キーを作成します。「Revenue Sensor」など、後で見分けがつく名前を付けてください。
- 2
読み取り権限だけを付与する
Transactions、Adjustments、Products、Addresses の読み取りアクセスにチェックを入れます。Addresses は Customers の下にあり、購入者の国を知るために必要なので、無関係に見えても外さないでください。書き込み権限は不要です。
- 3
キーを一度だけコピーする
Paddle はキーを作成時に一度しか表示しません。すぐにコピーしてください。紛失した場合は失効させて、新しいキーを作成します。
アカウントを接続する
- 1
キーを貼り付ける
Revenue Sensor のコンソールで Integrations → Paddle → Connect を開き、API キーを貼り付けます。Revenue Sensor はキーのプレフィックスから本番用かサンドボックス用かを判別し、続行する前にどちらを使うかを確認します。
- 2
製品を選ぶ
同期の単位はストアのアプリではなく Paddle の製品です。台帳に含めたい製品を選んでください。各製品は収益に独立した行として表示され、アプリに属するものであればそのアプリに紐付けられます。取得されるのは選んだものだけで、プランの枠に数えられるのも選んだものだけです。
- 3
初回同期の完了を待つ
Paddle は全履歴を保持しているため、初回同期では最大 1 年分の支払い済み取引と返金を遡って取り込みます。通常は数分で終わり、実行中はページを離れても構いません。
取り込まれるデータ
| 項目 | 備考 |
|---|---|
| 収益 | 支払い済みの取引。請求書の発行日ではなく、代金が回収された日に計上されます。製品別・日別・購入者の国別に、税抜きで表示されます。Google Play が Google の手数料を差し引く前の総額で表示されるのと同様に、Paddle 自身の手数料も差し引かれません。 |
| 税 | Paddle は merchant of record として売上税や VAT を徴収し、すべての明細行に記載しています。そのため税は別途取り込まれ、このソースでは税込み表示が利用できます。 |
| 返金とチャージバック | 承認された返金とチャージバックは、承認された日に収益から差し引かれ、参考として返金額としても記録されます。取り消されたチャージバックは金額を戻します。クレジットやチャージバック警告は返金として扱われません。 |
| 国 | 顧客の請求先住所から取得します。使用するのは国コードのみです。 |
Paddle のすべての通貨に対応
取引は請求時の通貨のまま取り込まれ、ほかのソースと同じように換算されます。JPY や KRW のような小数点を持たない通貨も正しく読み取られるため、日本での売上が実際の 100 分の 1 として報告されることはありません。
リアルタイム更新（任意）
Revenue Sensor は Paddle を 30 分ごとに同期します。新しい売上や返金を 1〜2 分以内に確認したい場合は、Paddle の通知先（notification destination）を当社に向けてください。数値はこれまでどおり Paddle の API から取得され、Webhook は「早めに同期する」合図になるだけです。
- 1
Webhook URL をコピーする
Revenue Sensor のコンソールで Paddle の接続を開きます。「Real-time updates」パネルにこの接続専用の URL が表示されるので、コピーします。
- 2
通知先を作成する
Paddle で Developer tools → Notifications → New destination に移動します。URL を貼り付け、種類に Webhook を選び、transaction、adjustment、subscription のイベントを購読します。
- 3
シークレットを保存する
通知先を作成すると、Paddle が署名用シークレットを表示します。それを「Real-time updates」パネルに貼り付けて保存してください。当社はこれを使ってすべての配信を検証し、署名のないものは破棄します。シークレットは暗号化して保存され、二度と表示されません。
トラブルシューティング
- キーが拒否される：Transactions、Adjustments、Products、Addresses の 4 つすべてに読み取りアクセスがあるか確認してください。Addresses のないキーは基本チェックは通りますが、同期で失敗します。
- 製品が一覧に出てこない：キーが別のアカウントのものか、本番のつもりがサンドボックスのキーになっています（またはその逆）。キーのプレフィックスでどちらか分かります。
- 売上が欠けている：取り込まれるのは支払い済みで完了した取引だけです。下書き、未払いの請求書、キャンセルされた取引はまだ収益ではありません。
- 収益が入金額より多く見える：想定どおりです。税は別に管理され、Paddle の手数料も差し引かれないため、この数値は Paddle の取り分を引く前の総収益です。
- 返金が売上と別の日に表示される：返金は承認された日に計上され、元の購入日には遡りません。