Skip to content
AppDues
Log in
Contact salesSign up

Google Play Billing のエッジケース対応ガイド

購入フローを起動し、結果を受け取り、承認してエンタイトルメントを付与する——この一連の流れだけを実装した課金処理は、実機のテストでは問題なく動いてしまうことがあります。ところが本番環境では、支払いが数時間から数日遅れる購入、承認されないまま残った購入、消費に失敗した消耗型商品、次回更新まで反映されないダウングレード、接続が切れた BillingClient など、サンプルコードの範囲外の状態が日常的に発生します。

ハッピーパスだけでは本番を支えられない理由

Android の公式サンプルは、即時に完了した購入を処理する形になっています。購入結果が OK で、purchaseState が PURCHASED であれば承認してアクセス権を渡す、という流れです。この実装が破綻するのは、購入が「成功」と「失敗」の二値ではないからです。支払い待ちのまま保留される購入、承認だけが取り残された購入、コンテンツは渡したが消費が済んでいない購入、次回更新日まで旧プランが有効なダウングレードが存在します。これらを放置すると、サポート問い合わせの増加、返金、そしてサブスクライバーの離脱につながります。

本ガイドでは、各エッジケースについて「なぜ起きるのか」「どう検知するのか」「どう処理するのか」を順に整理します。あわせて、状態ごとの判断チェックリストを用意しているので、実装の抜け漏れ確認に使ってください。

保留中の購入(PENDING):支払いが即時でないケース

コンビニでの現金支払い、銀行振込、一部のキャリア決済など、非同期の決済手段では購入がすぐには確定しません。この場合 Google Play は PURCHASED ではなく PENDING 状態の購入を返します。クレジットカードの利用率が低い市場では特に一般的で、アプリをグローバルに展開するなら避けて通れない状態です。

支払い方法ごとの処理時間の目安

以下は、保留中の購入が発生しやすい支払い方法と、処理時間の目安をまとめた参照用の表です。地域や決済事業者の状況によって実際の所要時間は変わるため、あくまで設計時の目安として扱い、最新の条件は Google Play の公式情報で確認してください。

保留状態の検知と、やってはいけないこと

PurchasesUpdatedListener は、完了済みの購入と同じように保留中の購入も受け取ります。違いは purchaseState フィールドです。PURCHASED なら支払い完了として処理し、PENDING なら保留として扱い、UNSPECIFIED_STATE ならバックエンドに状態を問い合わせます。

ここで守るべきルールは一つです。保留中の購入に対してエンタイトルメントを付与してはいけません。ユーザーはまだ支払いを終えていないからです。代わりに購入トークン・商品 ID・注文 ID・購入時刻を記録し、「支払い確認後に利用可能になる」ことを画面上ではっきり伝えます。

保留購入の完了をどう受け取るか

支払いが確認されると、アプリは onPurchasesUpdated または queryPurchasesAsync を通じて更新された購入を受け取り、purchaseState が PURCHASED になります。ここから承認とエンタイトルメント付与を進められます。

見落としやすいのは、支払い完了の時点でユーザーがアプリを開いていない可能性です。このケースはバックエンド側で Real-Time Developer Notifications(RTDN)を受けて処理します。以前保留だったトークンに対して ONE_TIME_PRODUCT_PURCHASED または SUBSCRIPTION_PURCHASED の通知が届いたら、バックエンドでエンタイトルメントを更新し、ユーザーへ通知します。

BillingClient で保留購入を有効化する

保留中の購入を扱うには、BillingClient の構築時に明示的な有効化が必要です。有効化しない場合、遅延支払いの購入は完全に失敗します。Play Billing Library 7 以降では enablePendingPurchases() の呼び出しが必須で、省略すると BillingClient の初期化自体が失敗します。

ITEM_ALREADY_OWNED:エラーの裏にある未承認購入

ITEM_ALREADY_OWNED は、ユーザーがすでに所有している非消耗型商品やサブスクリプションを再購入しようとしたときに返ります。しかし実際にこのレスポンスが起きる原因の多くは、ユーザーが二重購入を狙っていることではありません。過去の購入が承認されないまま放置されていることが原因です。Google Play では購入の承認が必須なので、承認されていない購入は「支払いは済んだが、アプリ側ではまだ確定していない」中途半端な状態で残ります。その状態で同じ商品を買おうとすると、Google Play は未承認の購入が残っていると判断して ITEM_ALREADY_OWNED を返します。

未承認購入が生まれる典型パターン

未承認の購入は、次のような場面で発生します。

  • 購入を受け取った直後、承認の前にアプリがクラッシュした
  • ネットワークエラーで承認呼び出しが完了しなかった
  • 購入フロー中にユーザーがアプリを強制終了した
  • 承認 API がエラーを返し、再試行されなかった

いずれもアプリ側の不具合というより、通信やプロセスの中断に起因します。だからこそ、起動時や接続時のリカバリー処理が欠かせません。

ITEM_ALREADY_OWNED をエラー表示で終わらせない

ITEM_ALREADY_OWNED を受け取ったときにエラーメッセージを出すのは、正しい対応ではありません。既存の購入をクエリし、未承認の購入があればそれを処理するのが正解です。queryPurchasesAsync で購入一覧を取得し、purchaseState が PURCHASED かつ isAcknowledged が false のものを通常の購入処理に流します。

この復旧パターンでは、以前の承認が失敗していたことをユーザーに知らせる必要はありません。ユーザーの視点では「購入」をタップしたら商品が手に入る、それだけです。

起動時に未承認購入を回収して予防する

最善の策は、問題が起きてから直すのではなく、アプリ起動時に未承認の購入を処理しておくことです。BillingClient の接続が正常に確立したタイミングで、INAPP と SUBS の両方の商品タイプについて購入をクエリし、未承認のものを処理します。これにより、取りこぼされていた購入がユーザーに影響を及ぼす前に回復されます。

消耗型購入:acknowledge と consume の役割の違い

ゲーム内通貨、追加ライフ、トークンパックのような消耗型商品では、承認(acknowledgment)と消費(consumption)の混同がバグの温床になります。どちらも消耗型商品に必要ですが、目的もタイミング要件も異なります。

承認は「購入したコンテンツを配信済み」と Google Play に伝える処理で、購入から3日以内に行う必要があります。期限を過ぎると自動的に返金されます。消費は購入をリセットし、ユーザーが同じ商品を再購入できるようにする処理です。消費しない限り再購入はできず、再購入を試みると ITEM_ALREADY_OWNED が返ります。消耗型商品では消費を行うべきで、消費処理は暗黙的に承認も兼ねます。

複数量購入で quantity を無視しない

Google Play は消耗型商品の複数量購入に対応しており、1回のトランザクションで同じ商品を複数個購入できます。数量は Purchase オブジェクトの quantity フィールドから取得できます。

ここで見落としやすいのが、quantity を無視して常に1ユニットだけ付与する実装です。たとえばユーザーが10個のトークンパックを購入したのに、アプリが1個しか付与しなければ、支払った分より少ないアイテムしか受け取れません。これがサポート問い合わせや返金リクエストの原因になります。複数量購入を有効にするには Google Play Console で該当商品の「Allow multi-quantity purchases(複数量購入を許可)」をオンにし、BillingFlowParams ではユーザーが選択できる最大数量を指定します。

consumeAsync の失敗を放置しない

ネットワークエラーなどで consumeAsync が失敗すると、ユーザーはコンテンツを受け取っているのに購入が消費されていない状態になります。この状態では、ユーザーが同じ消耗型商品を再購入できません。また、消費処理は暗黙的に承認も行いますが、消費が完了しないまま3日が経過すると購入が返金される可能性があります。

そのため、消費に失敗した購入トークンを記録し、再試行する仕組みを用意してください。BillingClient が接続されるたびに、未承認購入のリカバリーとあわせて保留中の消費処理を再試行するのが確実です。

サブスクリプションのダウングレードと日割り計算モード

ユーザーがプランを変更したときの課金挙動は、アップグレードかダウングレードか、そしてどのリプレースメントモードを指定したかによって変わります。特にダウングレードは、多くの開発者が想定していない挙動を示します。

ダウングレード(より安価なプランへの変更)のデフォルトは DEFERRED です。変更は即時ではなく次回の更新日に適用され、現在の請求期間が終わるまではユーザーは上位プランの機能を使い続けられます。

リプレースメントモードの選び方

モードごとに、変更の適用タイミング、課金への影響、向いている用途が異なります。以下の表を、プラン変更フローの設計判断に使ってください。

遅延ダウングレードの落とし穴

遅延ダウングレードでよくある誤りは、購入フローが完了した直後にサブスクリプション状態を確認し、新しいプランが反映されていると期待してしまうことです。DEFERRED モードでは、次回更新日まで元のサブスクリプションが元のプロダクト ID のまま有効で、新しいサブスクリプションが現れるのは更新後です。

つまり、エンタイトルメントのチェックではこの移行期間を考慮する必要があります。バックエンドに保留中のダウングレードがあるかを問い合わせ、あれば「現在のプラン」「変更後のプラン」「適用日」を画面に示すのが親切です。

プラン変更時の linkedPurchaseToken の扱い

サブスクリプションのリプレースメント(アップグレードまたはダウングレード)が処理されると、新しい購入トークンが生成されます。この新しい購入には、以前のサブスクリプションを参照する linkedPurchaseToken フィールドが含まれます。

バックエンドでは、linkedPurchaseToken があれば「新規購入ではなくプラン変更」と判断し、ユーザーの購入トークンを新しいものに更新したうえで、古いトークンを無効化します。古いトークンを無効化しないのはよくあるバグで、サブスクライバー数の水増しや誤った収益レポートにつながります。

ネットワーク障害と再試行戦略

課金処理はネットワークに依存しており、障害や遅延は避けられません。失敗しうる重要な処理には、購入フローそのもの、承認、消費、購入検証が含まれます。それぞれに再試行の設計が必要です。

承認の猶予期間と再試行

Google Play では購入の承認に3日間の猶予が設けられており、この期間内に承認しないと購入は自動的に返金されます。これはユーザー保護の仕組みですが、その分、承認ロジックは一時的な障害に耐えられる必要があります。

SERVICE_UNAVAILABLE、SERVICE_DISCONNECTED、ERROR のような一時的な失敗は再試行対象として記録し、それ以外の再試行できないエラーは調査用にログへ残す、という切り分けが有効です。

BillingClient の切断に備える

BillingClient はいつでも切断される可能性があり、切断中に実行した操作は失敗します。指数バックオフを用いた再接続ロジックを実装し、接続が回復したら未承認購入のリカバリーと保留中の消費処理の再試行をまとめて実行するのが定石です。

状態別チェックリスト:実装の抜け漏れ確認に

各エッジケースを、検知のきっかけと取るべきアクションで整理します。実装レビューの観点として使ってください。

  • PENDING を受け取った → 購入情報を記録し、エンタイトルメントは付与せず、支払い待ちであることを画面に表示する
  • PURCHASED かつ未承認の購入を見つけた → 承認し、エンタイトルメントを付与する(起動時と接続時に回収する)
  • ITEM_ALREADY_OWNED を受け取った → エラー表示ではなく、既存購入をクエリして未承認分を処理する
  • 消耗型商品を配信した → quantity 分を付与し、consumeAsync を実行する。失敗したらトークンを記録して再試行する
  • DEFERRED のダウングレードを検知した → 次回更新日まで旧プランが有効である前提でエンタイトルメントを判定する
  • linkedPurchaseToken を持つ購入を検知した → 新トークンへ移行し、旧トークンを無効化する
  • BillingClient が切断された → 指数バックオフで再接続し、回復後にリカバリー処理をまとめて実行する

混同しやすい失敗原因の見分け方

ITEM_ALREADY_OWNED と USER_CANCELED は、どちらも購入が成立しなかった結果として現れますが、意味はまったく異なります。USER_CANCELED はユーザー自身が購入を取りやめた状態で、アプリ側で特別な処理は不要です。一方 ITEM_ALREADY_OWNED は、ユーザーが購入を望んでいるのに、過去の未承認購入が邪魔をしている状態です。この違いを意識せず、どちらも同じエラー画面に流してしまうと、本来救えたはずの購入を取りこぼします。

同様に、PENDING を「購入失敗」として扱うのも誤りです。PENDING は失敗ではなく、支払い確認待ちの進行中状態です。ユーザーには「処理中」と伝え、完了時にエンタイトルメントが有効になることを案内してください。

課金基盤をマネージドサービスに任せる選択肢

ここまで見てきた各エッジケースには、Play Billing Library を直接使って解決する明確な方法があります。ただし、すべてを実装するための累積的な工数は小さくありません。クライアント側の処理、バックエンドでの RTDN 処理、再試行メカニズム、状態をまたいだ慎重なステート管理が必要になります。たとえば、保留中の購入を追跡するテーブル、承認と消費を自動化するワーカー、linkedPurchaseToken を突き合わせるバックエンド処理、指数バックオフ付きの再試行キュー、CustomerInfo に相当する状態のローカルキャッシュ——これらを個別に設計・運用するとなると、課金機能そのものより基盤の保守に時間を割くことになりかねません。マネージドの課金基盤を採用するかどうかは、こうした各機能を自前で持つコストと、外部サービスへの依存度を天秤にかけて判断するのが現実的です。導入を検討する際は、保留中の購入の追跡、承認と消費の自動処理、プラン変更時の linkedPurchaseToken の処理、ネットワーク再試行と状態のローカルキャッシュが、それぞれどの範囲までカバーされるのかを提供元の資料で確認してください。自前で構築するかマネージドサービスを使うかにかかわらず、これらのエッジケースを理解しておくことは、課金システムの安定性を判断するうえで欠かせません。

保留中の購入が発生しやすい支払い方法と処理時間の目安
支払い方法一般的な地域通常の処理時間
現金支払い(コンビニ)日本、メキシコ、インドネシア24〜48時間
銀行振込ドイツ、オランダ、ブラジル1〜3営業日
キャリア決済(一部のキャリア)各国数分〜数時間

処理時間は設計時の目安であり、地域・決済事業者の状況により変動します。最新の条件は Google Play の公式情報で確認してください。

サブスクリプションのリプレースメントモード比較
モード変更が適用されるタイミング課金への影響最適な用途
IMMEDIATE_WITH_TIME_PRORATION即時残り期間分が新しいプランにクレジットされるユーザーが即時にアクセスできるアップグレード
IMMEDIATE_AND_CHARGE_PRORATED_PRICE即時残り期間分に対して日割り請求公平な課金を伴うアップグレード
IMMEDIATE_AND_CHARGE_FULL_PRICE即時新しいプランの全額が請求され、新しい請求期間が開始プレミアムへのアップグレード
DEFERRED次回更新時即時の請求なしダウングレード
IMMEDIATE_WITHOUT_PRORATION即時次回更新まで追加請求なし同価格帯プラン間の移動や上位プランのトライアル

モードの挙動は Google Play の仕様に基づく参照情報です。実装時は最新の公式ドキュメントで確認してください。

Frequently asked questions

保留中の購入(PENDING)でもすぐにエンタイトルメントを付与してよいですか?

いいえ。PENDING は支払いがまだ確認されていない状態なので、エンタイトルメントを付与してはいけません。購入トークンや商品 ID を記録し、支払い確認後に PURCHASED へ遷移したタイミングで承認と付与を行います。ユーザーがアプリを開いていない場合は、RTDN を受けたバックエンド側で処理します。

ITEM_ALREADY_OWNED が返ってきたら、ユーザーにエラーを見せればよいですか?

エラー表示で終わらせるのは適切ではありません。原因の多くは過去の未承認購入が残っていることなので、queryPurchasesAsync で既存の購入を取得し、PURCHASED かつ未承認のものを通常の購入処理に流して復旧させます。あわせて起動時に未承認購入を回収しておくと、この状況自体を予防できます。

消耗型商品では acknowledge と consume のどちらを呼べばよいですか?

消耗型商品では consume を呼んでください。消費処理は暗黙的に承認も行います。承認は購入から3日以内が期限で、過ぎると自動返金されます。消費が失敗するとユーザーは同じ商品を再購入できなくなるため、失敗時はトークンを記録して再試行する仕組みを用意します。

ダウングレード直後に新しいプランが反映されないのはなぜですか?

ダウングレードのデフォルトは DEFERRED モードで、変更は次回更新日に適用されます。それまでは元のプロダクト ID のサブスクリプションが有効なため、購入フロー完了直後に状態を確認しても新プランは表示されません。バックエンドで保留中のダウングレードを確認し、適用日をユーザーに案内してください。