パートナーが管理するお支払い方法（PMFI）

オンボーディングフローでは、Twitterアカウント用のads.twitter.comアカウントを設定します。このアカウントは広告APIを介してパートナーによって管理でき、その広告費用はパートナーに請求されます。
 

パートナーの初期設定

新しいPMFI広告APIパートナーの初期設定プロセスには、必要な情報の交換により、最大3週間かかります。プロセスを開始するには、Twitterの技術担当者の連絡先、およびパートナーとの統合を管理するTwitterの連絡先に、次の情報を伝える必要があります。

• パートナーはPGP/GPGパブリックキーを共有する必要があります。広告APIパートナーとTwitterの間で共有シークレットキーを交換する必要があります。これを使用することにより、オンボーディングフロー中にデータが認証されます。
• 広告APIアクセスに使用されるTwitterアプリのapp_idまたはconsumer_secret。 developer.twitter.comでTwitterアカウントにログインしている場合は、アプリ管理画面から既存のTwitterアプリを表示、編集できます。Twitterアプリを作成する必要がある場合は、承認済みの開発者アカウントが必要です。 Twitterでは、本番環境とサンドボックス用に1つのアプリを作成でき、サンドボックス専用アクセス用に1つのアプリを任意で作成できます。Twitterアプリは、企業のパートナーが管理するTwitterユーザー名で作成する必要があります。
   

広告主のオンボーディングフロー

広告主のオンボーディングフローは、ウェブブラウザーを介して次の方法で処理されます。

1. ユーザーがパートナーのウェブサイトでオンボーディングフローを開始し、オンボードするユーザー名を入力します。
2. パートナーが、署名済みペイロードを使用してads.twitter.comのURLにユーザーをリダイレクトします。このペイロードには、パートナーのAPI app_id、オンボードされるTwitterユーザー名のTwitter user_id、コールバックURL、以下に記載のその他のフィールドが含まれます。
3. ユーザーは、標準のtwitter.comログインページを使用してads.twitter.comにログインするよう求められます。
4. ユーザーがログインすると、オンボーディングプロセスが開始されます。この手順には、広告の確認、アカウントの検証、その他の確認が含まれます。
5. すべてのオンボーディング作業が完了すると、ユーザーは、成功または失敗を示すペイロードとともに、広告APIパートナーによって提供されたコールバックURLにリダイレクトされます。ここでは3レッグ認証プロセスが実行されます。
    

オンボーディングリダイレクトペイロード

リダイレクトのURL:

https://ads.twitter.com/link_managed_account

リダイレクトURLは以下のパラメーターで呼び出されます。

コールバックURLのペイロード

ベースのリダイレクトURLは、アカウントリンクリクエストのcallback_urlパラメーターを使用して指定されます（上述を参照）。ads.twitter.comによって追加されるパラメーターは次のとおりです。

コールバックURLがアカウントリンクプロセスの対象となっているTwitterのuser_idに対してのみ有効であることを確認するには、リクエストに署名する際に、Twitter user_idを共有シークレットに追加します（&を使用）。
 

リクエストとコールバックURLへの署名

/link_managed_accountとコールバックURLへのリクエストが有効であることを確認するためには、発信側でリクエストに署名し、受信者がその署名を認証してからリクエストの処理を行うようにします。Twitterと管理パートナーの間で共有されているシークレットを使用してリクエストに署名することにより、各当事者は承認された相手から送信されたリクエストのみを受け入れることになります。

署名生成アルゴリズムは、OAuthで使用されているものと似ています。

次のように署名ベース文字列を作成します。

• HTTPメソッドを大文字に変換し、ベース文字列をこの値に設定します。
• ベース文字列に「&」を追加します。
• URLを（パラメーターなしで）パーセントエンコードし、それをベース文字列に追加します。
• ベース文字列に「&」を追加します。
• パーセントエンコードされたクエリ文字列を追加します（作成方法は後述を参照）。
• 署名されるすべてのキーと値をパーセントエンコードします。
• パラメーターのリストをキーのアルファベット順に並べ替えます。
• キーと値のペアごとに、次を実行します（パートナーリダイレクトURLの場合はprimary_promotable_user_idを使用）。
• パーセントエンコードされたキーをクエリ文字列に追加します。
• ベース文字列に「=」を追加します。
• パーセントエンコードされた値をクエリ文字列に追加します。
• パーセントエンコードされたキーと値のペアを「&」で区切ります。
• 前回に交換した共有シークレットをキーとし、ベース文字列を値として使用する、HMAC-SHA1アルゴリズムを使用して署名を生成します。
• 手順2の出力をBase64でエンコードし、末尾の改行文字を削除し、手順3で生成した署名をパーセントエンコードして、署名パラメーターのURLに追加します
   

署名の例

リンクアカウントリクエストへの署名

署名するURL。以下のGETリクエストを想定。

https://ads.twitter.com/link_managed_account?callback_url=https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&client_app_id=12345&fi_description=some%20name&promotable_user_id=1

このURLには次のパラメーターがあります。

callback_url = https://managingpartner.com/link_account_callback
client_app_id = 12345
fi_description = some name
promotable_user_id = 1

httpメソッドとパラメーターを持たないURLから構成されるベース文字列は、手順a～dでは次のようになります。

GET https://ads.twitter.com/link_managed_account

サブ手順eで生成されたクエリ文字列は、次のようになります。

callback_url=https://managingpartner.com/link_account_callback&client_app_id=12345&fi_description=some name&promotable_user_id=1

キーと値のペアはキー名で並べ替えられます。

パーセントエンコードされたクエリ文字列は次のようになります。

callback_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink_account_callback%26client_app_id%3D12345%26fi_description%3Dsome%2520name%26promotable_user_id%3D1

手順a～dとeを組み合わせた完全なベース文字列は次のようになります。

GET https://ads.twitter.com/link_managed_account&callback_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink_account_callback%26client_app_id%3D12345%26fi_description%3Dsome%2520name%26promotable_user_id%3D1

hmac-sha1アルゴリズムを使用し、「secret」という単語をキーとしてこれに署名します。結果はBase64でエンコードされ、最後の「 」なしで次のように表示されます（手順2と3）。KBxQMMSpKRrtg9aw3qxK4fTXvUc=

この署名は、署名パラメーターの元のURLの末尾にパーセントエンコードされて追加されます（手順4）。

https://ads.twitter.com/link_managed_account?callback_url=https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&client_app_id=12345&fi_description=some%20name&promotable_user_id=1&signature=KBxQMMSpKRrtg9aw3qxK4fTXvUc%3D

パートナーリダイレクトURLに署名（アカウントリンクリクエストコールバック）します。GETリクエストの場合に署名するURLは次のようになります。

https://managingpartner.com/link_account_callback?status=OK&account_id=ABC&funding_instrument_id=DEF

このURLには次のパラメーターがあります。

account_id = ABC、funding_instrument_id = DEF、status = OK

httpメソッドとパラメーターを持たないURLから構成されるベース文字列は、手順a～dでは次のようになります。

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&``

サブ手順eで生成されたクエリ文字列は、次のようになります。

account_id=ABC&funding_instrument_id=DEF&status=OK

パーセントエンコードされたクエリ文字列は次のようになります。

account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

手順a～dとeを組み合わせた完全なベース文字列は次のようになります。

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

hmac-sha1アルゴリズムを使用し、「secret」という単語と、元のリンクリクエストが行われたTwitterユーザーID「1」（上述のpromotable_user_id = 1）をキーとする「secret&1」でこれに署名します。

結果はBase64でエンコードされ、最後の「 」なしで次のように表示されます（手順2と3）。jDSHDkHJIFXpPLVxtA3a9d4bPjM=

この署名は、署名パラメーターの元のURLの末尾にパーセントエンコードされて追加されます（手順4）。

https://managingpartner.com/link_account_callback?&status=OK&account_id=ABC&funding_instrument_id=DEF&signature=jDSHDkHJIFXpPLVxtA3a9d4bPjM%3D

共有キーの使用と更新

署名アルゴリズムには、複数のキーで自身の処理を繰り返す機能が必要です。これにより、複数の共有キーを使用でき、定期的に共有キーを循環させることができます。
 

partner_managed_funding_instrumentの作成

fi_descriptionパラメーターが指定されており、同じ名前を持つ既存のpartner_managed_funding_instrumentがアカウントに存在しない場合は、新しいpartner_managed_funding_instrumentが作成され、すべての既存のpartner_managed_funding_instrumentが一時停止されます。

同じ名前のpartner_managed_funding_instrumentが存在する場合、新しいものは作成されません。
 

オンボーディングフローの呼び出しとトークンの更新の繰り返し

APIアクセストークンがなくなった場合は、オンボーディングフローを繰り返すことができます。オンボーディングフローを実装する場合は、ユーザーがログインしている必要があります。アカウントがpromable_user_idと一致し、関連する広告アカウントが見つかり、すべてに問題がない場合は、ユーザーはコールバックURLにリダイレクトされ、パートナーはOAuthフローを開始してアクセストークンを取得できます。
 

リダイレクト不可能なエラーフロー

アカウントリンクURLが無効なパラメーターで呼び出された場合、無効または期限切れのパラメーターが指定されたときにOAuthフローに表示されるページに似たページが表示されます。
 

PMFIへの継続的な更新

広告主のオンボードが完了すると、PUT accounts/:account_id/funding_instruments/:funding_instrument_idエンドポイントを使用してお支払い方法を管理できるのは、それを管理するパートナーのみになります。