非領収書支払い処理 (レガシエコノミー)

[アーティクル]
07/28/2023

Important

Economy v1 API はメンテナンスモードであり、新機能は受け取らず、バグ修正のみを受け取ります。 v1 API は、当面維持されます。 次のバージョンの PlayFab エコノミーの詳細については、｢エコノミー v2 の概要」をご覧ください。

さまざまなプラットフォームに向けた領収書の検証に加えて、PlayFab は領収書または資格ベースのシステムを使用しない支払いプロバイダーによる購入を有効化するメカニズムを提供しています。これにより、Facebook、PayPal、Xsolla、Steam などのプロバイダーが含まれます。

このチュートリアルでは、カートスタイルの支払いシステムを紹介することで、以下の方法を説明します。

プレイヤーが購入する一連のグッズを定義する。
選択したプロバイダーによってプレイヤーを処理する。
支払いが正常に処理され、適切なアイテムがプレイヤーのインベントリに追加されたことを検証する。
さらに、チュートリアルではプロセスのプレイヤープロバイダー部分についても説明し、購入を完了する方法の完全な概要を示します。

以下の図は、支払いフローで使用される API 呼び出しの概略です。

PlayFab - 支払い API フロー

支払いプロバイダーを設定する

実際に支払いを処理するロジックを開始する前に、最初に目的の支払いプロバイダーを設定する必要があります。

そのためには以下を実行します。

PlayFab ゲームマネージャーで自分のゲームを選択します。
[追加コンテンツ] タブを選択します。

追加コンテンツマーケットプレースに移動し、支払いプロバイダーを含むすべてのサードパーティーの統合を見つけることができます。

注意

Facebook や Steam など、一部のプロバイダーは支払い処理以上の機能を提供するため、このチュートリアルの「プラットフォーム」セクションにあります。

使用するプロバイダーを選択します。
次に、それぞれに対して[Install] (インストール) オプションを選択します。
要求される情報 (通常はアプリケーションと秘密キー) を入力しますが、各プロバイダーに固有の要件があります。

注意

この情報により、Microsoft がお客様に代わってプロバイダーのサービスと通信でき、購入を開始してステータスを確認できます。

これが完了すると、支払いフローの実装を開始できます。

PlayFab API の呼び出し

このプロセスに向けたクライアントからの一連の呼び出しは、ほとんどの領収書のない支払いプロバイダーで非常に似通っています。

StartPurchase - 購入するグッズのリストを作成します。
PayForPurchase - 支払いプロバイダーを確立し、支払い価格をロックします。
ConfirmPurchase - 購入が正常に完了したかどうかを検証し、必要に応じてグッズがプレイヤーに追加されたことを確認します。

注意

例外は Xsolla で、このチュートリアルの最後に個別に取り上げます。

以下の例では、{{TitleID}} や {{SessionTicket}} などのフィールドがあります。自分のコードでは、これらの値を適切なゲームの値とプレイヤーの認証チケットに置き換える必要があります。

購入を開始する

購入フローを通して、プレイヤーが購入する、ゲームカタログ内で定義された一連のグッズを処理することになります。

これがグッズのカートであり、PlayFab Client API メソッド StartPurchase への呼び出しによって定義し、プロセスを開始します。

PlayFabClientAPI.StartPurchase(new StartPurchaseRequest() {
    CatalogVersion = "IAP1_0",
    Items = new List<ItemPurchaseRequest>() {
        new ItemPurchaseRequest() {
            ItemId = "BigBagOfGold",
            Quantity = 1,
            Annotation = "Purchased via in-game store"
        }
    }
}, result => {
    // Handle success
}, error => {
    // Handle error
});

この例では、ゲームカタログで IAP1_0 - BigBagOfGold の ID で定義されているアイテムを使ってカートを作成します。これは、ゲームカタログで定義される ItemId です。

プレイヤーはこれらのうち 1 つのみを購入したいと考えています。アイテムがどのようにプレイヤーのインベントリに追加されるかを示すために注釈を使用します。これは、後のレビューに役立ちます。

注意

また、StoreId パラメーターを含めることで、この購入ではゲームで定義したストアの価格を使用することを指定することができます。

StartPurchase 呼び出しの戻り値には、カタログのアイテムの DisplayName と Description の値、定義された価格、プレイヤーの仮想通貨の残高など、多くの情報が含まれています。

しかし、次の手順に必要な主な情報は OrderId (この購入を一位に識別します) と、PaymentOptions に示される、使用する特定のプロバイダーです。

注意

タイトルに対して有効化した支払いプロバイダーのみが PaymentOptions に示されます。

{
  "code": 200,
  "status": "OK",
  "data": {
    "OrderId": "1234567890ABCDEF",
    "Contents": [{
      "ItemId": "BigBagOfGold",
      "ItemInstanceId": "ABCDEF1234567890",
      "DisplayName": "A hefty sack of gold",
      "Description": "Why, it’s a stonking great bag of shiny!",
      "VirtualCurrencyPrices": {
        "RM": 999
      }
    }],
    "PaymentOptions": [{
        "Currency": "RM",
        "ProviderName": "Facebook",
        "Price": 999,
        "StoreCredit": 0
      },
      {
        "Currency": "RM",
        "ProviderName": "PayPal",
        "Price": 999,
        "StoreCredit": 0
      },
      {
        "Currency": "RM",
        "ProviderName": "Steam",
        "Price": 999,
        "StoreCredit": 0
      }
    ],
    "VirtualCurrencyBalances": {
      "VC": 0
    }
  }
}

支払いプロバイダーを確立する: Web フックプロバイダー

Facebook

通常、この時点でのフローはどの支払いプロバイダーを使用するかを PlayFab に指定することです。これは、サービスがそのプロバイダーと通信し、トランザクションに関する情報を設定できるようにするためです。

この手順の例外は Facebook です。 Facebook は、購入が最初にFacebook のサービスで開始されることを要求します。その後、PlayFab などのサードパーティーサービスは、Facebook が提供するトランザクション識別子を使用して購入のステータスを確認できます。

ストア、カタログ、アイテム ID が英数字でない場合、以下のコードで示すように、OpenGraphProduct URL を構築する際に HTML/URL でエンコードする必要があります。

FB.ui({
    method: 'pay',
    action: 'purchaseitem',
    product: "https://{{TitleId}}.playfabapi.com/OpenGraphProduct/{{TitleId}}/{{StoreId}}/IAP1_0/BigBagOfGold",
    request_id: "1234567890ABCDEF"
}, function (response) {
    console.log('Payment completed', response);
    print(response);
    if (response.payment_id) {
        facebookPurchaseId = response.payment_id;
        payForOrder(); // This is a function call you need to write
                       // which makes the call to the Client API PayForPurchase
                       // (see below)
    }
});

この呼び出しを実行する際、Facebook では製品の大文字と小文字が区別されることを忘れないでください。

特に、PlayFab のゲームの正しいタイトル ID で置き換える必要がある TitleId は、通常は Facebook のサービスで小文字で表されます。 Facebook で正しい製品が見つからない問題が発生した場合は、このページに示すように、GET リクエストを使用して製品を手動で取得してください。

さらに、フローの前半の値を使用していることを確認する必要もあります。

購入されるアイテムが含まれる、PlayFab で定義したカタログの CatalogID (IAP1_0)。
購入されるゲームの PlayFab カタログアイテムの itemID (BigBagOfGold)。
このプロセスの最初に StartPurchase への呼び出しから返された OrderID (1234567890ABCDEF)

正常な応答では、Facebook によって payment_id が返されます。これは、次に ProviderTransactionId としてクライアント API メソッド PayForPurchase の呼び出しで使用できます。

const string paymentId = "_SOME_PAYMENT_ID" ;
PlayFabClientAPI.PayForPurchase(new PayForPurchaseRequest() {
    OrderId = "1234567890ABCDEF",
    ProviderName = "Facebook",
    Currency = "RM",
    ProviderTransactionId = paymentId
}, result => {
    // Handle success
}, error => {
    // Handle error
});

これにより、簡単な確認が返されます。

{
    "code": 200,
    "status": "OK",
    "data": {
        "OrderId": "1234567890ABCDEF",
        "Status": "Init",
        "PurchaseCurrency": "RM",
        "PurchasePrice": 999,
        "CreditApplied": 0
    }
}

これによってループが完了し、式の両側で PlayFab を購入に接続し、ステータスをクエリできるようになります。

Facebook デベロッパーポータル (https://developers.facebook.com/docs/payments/overview) で、Facebook の支払いシステムの詳細を確認できます。

Facebook の支払いのその他の側面は、タイトルが支払いに Web フックを使用し、支払いステータスに対するリアルタイムの変更通知を有効にするという要件です。

一部のケースでは支払いに非常に長い時間がかかるため、Facebook モデルではこれが必須です。幸い、これは簡単です。 Facebook でのタイトルの設定時に、コールバック URL として以下を入力します。

https://{{TitleId}}.playfabapi.com/ThirdPartyPayments/FacebookPaymentUpdate

{{TitleId}} は、PlayFab のゲームのタイトル ID です (例: https://aaa.playfabapi.com/ThirdPartyPayments/FacebookPaymentUpdate)。

Facebook の設定でトークンを指定する必要はありません。コールバック URL を設定し、ゲームマネージャーの [Facebook Add-ons] (Facebook の追加コンテンツ) ページで PlayFab の設定が正しいことを確認するだけで、設定は完了です。

Facebook がこの Webhook を使用して支払いの状態を更新すると、注文の状態が PlayFab で更新されます。成功した場合)、適切な項目がプレイヤーインベントリに追加されます。

注意

セキュリティ: この API は、Facebook に再度呼び出しを実行し、安全にトランザクションを認証および検証するように指示する PlayFab のプロンプトであることに注意してください。 Facebook での支払いを回避するためのハッカーの裏口ではありません。

Facebook を支払いプロバイダーとして使用する場合、以下に示すように、クライアントが購入を確認することが引き続き重要です。

支払いプロバイダーを確立する: Web フックを使用しないプロバイダー

Steam

すべての支払いプロバイダーで、Steam は統合が最も簡単です。

PlayFabClientAPI.PayForPurchase(new PayForPurchaseRequest() {
    OrderId = "1234567890ABCDEF",
    ProviderName = "Steam",
    Currency = "RM"
}, result => {
    // Handle success
}, error => {
    // Handle error
});

PayForPurchase 呼び出しの結果として、PlayFab は Steam によって提供される Web メソッドを使用してそのサービスでの購入を開始します。これにより、ユーザーには Steam クライアントからの購入確認ダイアログが表示されます。

そのため、クライアント API PayForPurchase 呼び出しへの応答を受け取ると同時に、ユーザーは支払いを承認するように求められます。

{
    "code": 200,
    "status": "OK",
    "data": {
        "OrderId": "1234567890ABCDEF",
        "Status": "Init",
        "PurchaseCurrency": "RM",
        "PurchasePrice": 999,
        "CreditApplied": 0
    }
}

Steam はコールバックメカニズムを使用して購入プロセスの完了をタイトルに知らせるため、MicroTxnAuthorizationResponse_tコールバックに対するコールバックハンドラーを登録する必要があります。

登録済みの Steam のデベロッパーは、 https://partner.steamgames.com/documentation/MicroTxn#WebPurchasing で、このプロセスに関する詳細情報を取得できます。

コールバックを受け取ると、タイトルは「最後の手順: 購入を確認する」セクションに示す ConfirmPurchase 呼び出しに進みます。

PayPal

PayPal では、PayForPurchase 呼び出しは事実上 Steam と同じです。

PlayFabClientAPI.PayForPurchase(new PayForPurchaseRequest() {
    OrderId = "1234567890ABCDEF",
    ProviderName = "PayPal",
    Currency = "RM"
}, result => {
    // Handle success
}, error => {
    // Handle error
});

ただし、この場合は、支払いリクエストをプレイヤーに送信する便利なクライアントアプリケーションはありません。

PayPal では、プレイヤーに PayPal インターフェイスを提供し、購入に同意することを確認してもらう必要があります。ただし、すべての詳細に対応するため、このプロセスは背後では PayPal Express チェックアウトを使用します。

必要なのは、PurchaseConfirmationPageURL として返される購入確認ページをユーザーに提示するだけです。

{
    "code": 200,
    "status": "OK",
    "data": {
        "OrderId": "1234567890ABCDEF",
        "Status": "Init",
        "PurchaseCurrency": "RM",
        "PurchasePrice": 999,
        "PurchaseConfirmationPageURL": "https://...",
        "CreditApplied": 0
    }
}

この場合、ブラウザーウィンドウが終了したら、PlayFab で購入を確認する必要があることを意味します。

最後の手順: 購入を確認する

プロセスの最後は、PlayFab で購入プロセスを完了し、購入されたアイテム (該当する場合) をプレイヤーのインベントリに追加することです。

一部のプロバイダーの場合、この段階で、タイトルは購入が正常に完了されたかどうかをすでに把握しています。

いずれの場合も、クライアント API メソッド ConfirmPurchase の呼び出しは、支払いが完了してまだ追加されていない場合に、プレイヤーのインベントリにアイテムを追加するだけです。

PlayFabClientAPI.ConfirmPurchase(new ConfirmPurchaseRequest() {
    OrderId = "1234567890ABCDEF"
}, result => {
    // Handle success
}, error => {
    // Handle error
});

この時点で、注文が正常に完了した場合は、クライアント API StartPurchase への呼び出しによって設定されたカート内のアイテムを反復処理します。

これによってアイテムがプレイヤーのインベントリに追加され、購入されたアイテムに関する情報がタイトルに返されます。

{
    "code": 200,
    "status": "OK",
    "data": {
        "OrderId": "1234567890ABCDEF",
        "Status": "Succeeded",
        "PurchaseDate": "2016-07-19T09:04:28Z",
        "Items": [{
            "ItemId": "BigBagOfGold",
            "ItemInstanceId": "ABCDEF1234567890",
            "CatalogVersion": "IAP1_0",
            "DisplayName": "A hefty sack of gold",
            "UnitCurrency": "RM",
            "UnitPrice": 999
        }]
    }
}

トランザクションの状態

背後では、注文の状態は何度も変化します。完全な一覧を以下に示します。

注意

特定のプロバイダープロセスによっては、3 つの購入処理 API 呼び出しのいずれの結果でも一部の状態は表示されません。ここにはすべてを網羅するために記載します。

CreateCart - 注文オブジェクト自体はクライアント API StartPurchase の応答で返されませんが、その時点で作成されています。この段階で、アイテムと価格はオブジェクトに保存されますが、いずれの支払いプロバイダーにも送信されていません。
Init - これは注文が支払いプロバイダーに送信されたものの、まだプレイヤーによって承認されていない場合のステータスです。
Approved - この状態は、プレイヤーが支払いを承認したものの、PlayFab がまだプレイヤーのインベントリにアイテムを追加していない場合に一時的に発生します。 この状態は、完全を期すためこのリストに含まれていますが、タイトルにこの状態の注文が表示されることはありません。
Succeeded - これは、注文が正常に完了したことを示しています。プレイヤーが支払いを承認し、すべてのインベントリアイテムがプレイヤーのインベントリに追加されました。
FailedByProvider - 何らかの理由でプロバイダーが支払いを拒否した場合 (プレイヤーによる支払いの拒否も含む)、注文はプロバイダーによる失敗と見なされます。
DisputePending - 支払いプロバイダーが PlayFab に、支払いに未解決の問題があることを通知しました。
RefundPending - 支払いプロバイダーが PlayFab に、返金リクエストが発生したことを通知しました。この段階では、返金は実際に実行されていません。
Refunded - 注文は返金されました。ほとんど (またはすべて) の場合、支払いプロバイダーはこの情報を直接デベロッパーにも提供します。状態は、アイテムが消耗品かどうか (すでに消費されている場合があります) など、多くの要因によって異なります。
RefundFailed - 返金がリクエストされましたが、支払いプロバイダーによって拒否されました。 PlayFab は、これに関して追加の情報を提供することはできません。そのため、詳細が必要な場合は、デベロッパーは直接支払いプロバイダーに問い合わせる必要があります。
ChargedBack - このステータスは支払いプロバイダーに応じて異なり、注文に問題があるか、支払いが取り消されていることを示している場合があります。ここでも、注文の具体的な詳細は、支払いプロバイダーに問い合わせる必要があります。
FailedByPlayFab - このステータスは、支払いプロセスで予期しない障害が発生したことを示しています。このステータスが返されたら、タイトルは前回の支払い API 呼び出しを再試行する必要があります。それでも問題が解決しない場合は、サポートフォーラムに問題とそれに関するすべての詳細 (タイトル ID、PlayFab ID、注文 ID) を投稿することをお勧めします。

Xsolla での支払いを承認する

Xsolla の場合、プロセスは異なります。上記のコードフローは使用せず、代わりに Xsolla 支払フローを使用します。次に説明します: https://developers.xsolla.com/doc/in-game-store/extensions/playfab-integration/。

タイトルを構成して Xsolla の支払いサービスを使用するために、Xsolla の販売者 ID、プロジェクト ID、販売者 API キーが必要です。

まず、追加コンテンツのマーケットプレースの Xsolla ページのリンクを使用して、Xsolla アカウントにサインインします。
その構成ページを設定したら、次の手順は Xsolla サービスでグッズのカタログを作成することです。
Xsolla の各アイテムの item_code が PlayFab カタログ内のアイテム ID と一致することを確認します。これらは、購入を完了し、プレイヤーインベントリに正しいアイテムを安全に追加するために使用される識別子です。
Xsolla カタログで仮想アイテムのリストを設定するには、インストラクションの前半に記載した Xsolla の説明書をご覧ください。

購入を開始する (Xsolla)

購入する準備ができたら、GetPaymentToken API 呼び出しを使用し、TokenProvider として指定して、Xsolla サービスからトークンをリクエストします。

PlayFabClientAPI.GetPaymentToken(new GetPaymentTokenRequest() {
    TokenProvider = "xsolla"
}, result => {
    // Handle success
}, error => {
    // Handle error
});

呼び出しによって、次の手順で必要な Xsolla トークンである ProviderToken と、PlayFab の OrderId が返されます。背後では、この呼び出しによって Xsolla とのトランザクションが開始されます。

{
    "code": 200,
    "status": "OK",
    "data": {
        "ProviderToken": "1234567890ABCDEF",
        "OrderId": "1234567890ABCDEF"
    }
}

購入を完了する (Xsolla)

次に、クライアントはトークンを Xsolla に渡し、支払いプロセスを開始する必要があります。トークンは、以下のいずれかの URL を使用して Xsolla に渡すことができます。

サンドボックスの支払い:

https://sandbox-secure.xsolla.com/paystation3/?access_token=[TOKEN]

ライブ支払い

 https://secure.xsolla.com/paystation3/?access_token=[TOKEN]

これを実行すると、Xsolla インターフェイスでの購入が完了します。

ここでも、Xsolla のインターフェイスの使用について質問があれば、インストラクションの前半に記載した Xsolla の説明書をご覧ください。

完了したら、それ以上のアクションは必要ありません。 Xsolla と PlayFab は Webhook 呼び出しを交換します。 PlayFab はプレイヤーのインベントリに購入されたアイテムを追加し、適切なイベントを PlayStream に投稿することで購入を完了します。

クライアント API GetPurchase 呼び出しをポーリングすることで、トランザクションのステータスを確認できます (上記の完全なリストを参照してください)。

ほとんどの場合、このプロセスが完了するまでに 2-3 秒より長くかかることはありません。

PlayFabClientAPI.GetPurchase(new GetPurchaseRequest()
{
    OrderId = "1234567890ABCDEF"
}, result =>
{
    // Handle success
}, error =>
{
    // Handle error
});

{
    "code": 200,
    "status": "OK",
    "data": {
        "OrderId": "1234567890ABCDEF",
        "PaymentProvider": "Xsolla",
        "TransactionStatus": "Succeeded",
        "PurchaseDate": "2017-06-07T00:00:00Z"
    }
}

最終的な注意事項

1 つ注意が必要なのは、プロバイダーによっては支払いに長い時間がかかることです。

クライアント API ConfirmPurchase への呼び出しの応答で購入のステータスが Init のままの場合、再クエリする前に少し時間を置いてください。ここでのベストプラクティスは、プロセスの開始時に OrderId を保存し、結果をクエリする際に指数バックオフを使用することです。

ステータスが「Init」の場合は、クライアント API ConfirmPurchase への呼び出しを再試行する前に 1 分間待ち、その後最大値に達するまで 2 分、4 分、8 分と待ってください。 完了したトランザクションの確認オプションを含めると、ユーザーはそのタイマーをリセットできます。

最後に、支払いプロバイダーによる購入をテストする目的でサンドボックスモードを使用できます。

これを実行するには、PlayFab ゲームマネージャーの [Title’s Add-on] (タイトルの追加コンテンツ) タブで [Use sandbox purchase testing] (サンドボックスの購入テストを使用) オプションをチェックしてください。

次の方法で共有

非領収書支払い処理 (レガシエコノミー)

支払いプロバイダーを設定する

PlayFab API の呼び出し

購入を開始する

支払いプロバイダーを確立する: Web フックプロバイダー

Facebook

支払いプロバイダーを確立する: Web フックを使用しないプロバイダー

Steam

PayPal

最後の手順: 購入を確認する

トランザクションの状態

Xsolla での支払いを承認する

購入を開始する (Xsolla)

購入を完了する (Xsolla)

最終的な注意事項

フィードバック

その他のリソース

次の方法で共有

非領収書支払い処理 (レガシ エコノミー)

支払いプロバイダーを設定する

PlayFab API の呼び出し

購入を開始する

支払いプロバイダーを確立する: Web フック プロバイダー

Facebook

支払いプロバイダーを確立する: Web フックを使用しないプロバイダー

Steam

PayPal

最後の手順: 購入を確認する

トランザクションの状態

Xsolla での支払いを承認する

購入を開始する (Xsolla)

購入を完了する (Xsolla)

最終的な注意事項

フィードバック

その他のリソース

非領収書支払い処理 (レガシエコノミー)

支払いプロバイダーを確立する: Web フックプロバイダー