レシートを伴わない支払い処理 (Legacy Economy)

Economy v1 API はメンテナンスモードにあり、新機能は追加されず、バグ修正のみが行われます。v1 API は当面の間、維持されます。 PlayFab Economy の次のバージョンの詳細については、Economy v2 の概要を参照してください。

各種プラットフォームのレシート検証に加えて、PlayFab はレシートやエンタイトルメントベースのシステムを使用しない支払いプロバイダーを介して購入を可能にするメカニズムを提供します。これには、Facebook、PayPal、Xsolla、Steam などのプロバイダーが含まれます。このチュートリアルでは、このカートスタイルの支払いシステムの使用手順を説明し、次のことを行う方法を示します。

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

以下の画像は、支払いフローで使用される API 呼び出しの概要を示しています。

支払いプロバイダーのセットアップ

実際に支払いを処理するロジックを始める前に、まず意図する支払いプロバイダーを設定する必要があります。そのためには:

PlayFab Game Manager でゲームを選択します。
Add-ons タブを選択します。

これで Add-ons Marketplace に移動し、支払いプロバイダー を含むすべてのサードパーティ統合を確認できます。

Facebook や Steam などの一部のプロバイダーは、単に支払いを処理する以上のことを行い、このチュートリアルの Platforms セクションでも取り上げます。

使用したい プロバイダー を選択します。
各プロバイダーで Install オプションを選択します。
要求された情報 (通常はアプリケーションキーとシークレットキー) を入力します。ただし、プロバイダーごとに独自の要件があります。

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

完了したら、支払いフローの実装を開始する準備が整います。

PlayFab API 呼び出し

クライアント側では、このプロセスの呼び出しシーケンスはほとんどのレシートを伴わない支払いプロバイダーで類似しています。

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

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

以降の例では、{{TitleID}} や {{SessionTicket}} のようなフィールドが表示されます。お客様のコードでは、これらの値をご自身のゲームに適した値やプレイヤーの認証チケットに置き換える必要があります。

購入の開始

購入フロー全体を通じて、プレイヤーが購入したいゲームカタログ内の定義済みの商品セットを扱います。これは、商品の “カート” であり、PlayFab クライアント 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
});

この例では、ID IAP1_0 のゲームカタログで定義されたアイテム BigBagOfGold をカートに入れています。これはゲームカタログで定義された ItemId です。プレイヤーはこのアイテムを 1 つ だけ購入したいと考えています。annotation は、アイテムがどのようにプレイヤーインベントリに入ったかを示すために使用され、後の確認に役立ちます。

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

支払いプロバイダーの設定: Webhook プロバイダー

Facebook

通常、この時点でのフローは、どの支払いプロバイダーを使用するかを PlayFab に伝えることです。これは、PlayFab サービスがプロバイダーと通信し、トランザクションに関する情報を設定できるようにするためです。 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 では product が 大文字と小文字を区別する ことに注意してください。特に、TitleId は PlayFab におけるゲームの 正しい タイトル ID に置き換える必要がありますが、Facebook のサービスでは通常小文字です。Facebook が正しい製品を見つけられない問題が発生した場合は、こちらのページに示されているように GET リクエストを使用して手動で製品を取得してみてください。さらに、以前のフローで得た次の値も使用する必要があります。

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

応答が成功すると、Facebook は payment_id を返します。これを、クライアント API メソッド PayForPurchase の呼び出しの ProviderTransactionId として使用できます。

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 支払いシステムの詳細については、Facebook Developer Portal をご覧ください: https://developers.facebook.com/docs/payments/overview Facebook Payments のもう 1 つの側面は、支払いステータスへのリアルタイム変更通知を有効にするため、タイトルが webhook を使用する必要があるということです。これは Facebook のモデルでは必要です。というのも、支払いは場合によっては非常に長い時間がかかることがあるからです。幸い、これは簡単です。Facebook のタイトルセットアップで、Callback URL として次のように入力します。

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

ここで {{TitleId}} は PlayFab におけるゲームの タイトル ID です (例: https://aaa.playfabapi.com/ThirdPartyPayments/FacebookPaymentUpdate)。 Facebook のセットアップでトークンを指定する必要はありません - Callback URL を設定し、Game Manager の Facebook Add-ons ページで PlayFab のセットアップが正しいことを確認するだけで完了です。 Facebook がこの webhook を使用して支払いのステータスを更新すると、PlayFab の注文ステータスが更新されます。成功した場合は、適切なアイテムがプレイヤーのインベントリに追加されます。

セキュリティ: この API は PlayFab が Facebook に再度呼び出してトランザクションを安全に認証・検証するためのトリガーです。ハッカーが Facebook の支払いをバイパスするためのバックドアではありません。

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

支払いプロバイダーの設定: Webhook 以外のプロバイダー

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 Checkouts を使用していますが、詳細はすべて PlayFab で処理します。必要な作業は、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 キーが必要です。

開始するには、Add-ons Marketplace の Xsolla ページのリンクを使用して Xsolla アカウントに登録します。
その構成ページを設定したら、次のステップは Xsolla サービスで商品のカタログを作成することです。
Xsolla の各アイテムの item_code が、PlayFab カタログのアイテム ID と一致することを確認してください。これらは、購入を完了し、適切なアイテムを安全にプレイヤーインベントリに追加するために使用される識別子です。
Xsolla カタログで仮想アイテムのリストを設定するには、この手順の前半で提供したドキュメントを参照してください。

購入の開始 (Xsolla)

購入する準備ができたら、GetPaymentToken API 呼び出しを使用し、TokenProvider として Xsolla を指定して 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 と 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 Game Manager の タイトル用アドオン タブから Use sandbox purchase testing オプションをオンにします。

XBOX Services

PlayFab

Economy (Legacy) のレシートを伴わない支払い処理

レシートを伴わない支払い処理 (Legacy Economy)

支払いプロバイダーのセットアップ

PlayFab API 呼び出し

購入の開始

支払いプロバイダーの設定: Webhook プロバイダー

Facebook

支払いプロバイダーの設定: Webhook 以外のプロバイダー

Steam

PayPal

最終ステップ: 購入を確認する

トランザクションの状態

Xsolla を使った支払いの受諾

購入の開始 (Xsolla)

購入の完了 (Xsolla)

最終メモ

​レシートを伴わない支払い処理 (Legacy Economy)

​支払いプロバイダーのセットアップ

​PlayFab API 呼び出し

​購入の開始

​支払いプロバイダーの設定: Webhook プロバイダー

​Facebook

​支払いプロバイダーの設定: Webhook 以外のプロバイダー

​Steam

​PayPal

​最終ステップ: 購入を確認する

​トランザクションの状態

​Xsolla を使った支払いの受諾

​購入の開始 (Xsolla)

​購入の完了 (Xsolla)

​最終メモ

レシートを伴わない支払い処理 (Legacy Economy)

支払いプロバイダーのセットアップ

PlayFab API 呼び出し

購入の開始

支払いプロバイダーの設定: Webhook プロバイダー

Facebook

支払いプロバイダーの設定: Webhook 以外のプロバイダー

Steam

PayPal

最終ステップ: 購入を確認する

トランザクションの状態

Xsolla を使った支払いの受諾

購入の開始 (Xsolla)

購入の完了 (Xsolla)

最終メモ