Meta Pay APIを利用する

Meta Payの決済を処理する際には、Meta Pay APIでWebhooksを呼び出すことにより、認証や返金などの決済取引アクティビティをMetaに通知する必要があります。決済取引アクティビティは、顧客のFacebookアカウントの[注文と支払い]ページに表示されます。

MetaのAPIの使い方について詳しくは、Graph APIの概要をご覧ください。また、下記で説明されているAPIは、標準のGraph APIホストURL (https://graph.facebook.com)を基準にしていることに注意してください。その他の全般情報については、Meta Pay統合の概要をご覧ください。

オンボーディング

Meta Pay APIの利用を開始するには、その前に次のことを完了していなければなりません。

• 一般的なオンボーディングステップを完了する
• Meta Payの決済処理を確認する

Meta Pay APIを呼び出す

一般的なオンボーディングステップの一部として、Meta for Developersポータルで新しいアプリを作成します。アプリを作成すると、アプリのアプリIDとapp secretを取得できます。

Meta Pay APIの呼び出しごとに、アプリIDとapp secretから派生したアプリアクセストークンが必要になります。アプリアクセストークンは、access_tokenクエリパラメーターではなくAuthorizationヘッダーを使って送信します。Meta Pay APIは、ユーザートークンが使われている呼び出しは却下します。

例えば、次のコードを使います。

Authorization: OAuth <APP_ACCESS_TOKEN>

署名

Meta Pay APIに対するすべてのHTTPリクエストには、FBPAY_SIGNATUREリクエストヘッダーが含まれていなければなりません。このヘッダーの値は、ES256アルゴリズムを使ったJSON Web Signature (JWS)オブジェクトで、コンパクトシリアル化され、(https://tools.ietf.org/html/rfc7515#appendix-Fに従って)デタッチされたペイロードです。このペイロード値がHTTP POSTリクエスト本文です。JWS署名キーは、x5cヘッダーで識別されなければなりません。これは、パートナーの信頼されたルートにつながる証明書を含んでいなければなりません。パートナーのルート証明書は、オンボーディングプロセスの一環でMetaに共有されています(Meta Pay API署名証明書と呼ばれます)。

署名があるリクエストの例

curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "FBPAY_SIGNATURE: eyJhbGciOiJFUzI1NiIsIng1YyI6WyJNSUlCaERDQ0FTcWdBd0lCQWdJQkFUQUtCZ2dxaGtqT1BRUURBakFoTVI4d0hRWURWUVFEREJad1lYSjBibVZ5SUhOcFoyNWhkSFZ5WlNCalpYSjBNQjRYRFRJd01EY3hNekl5TWpVek1Gb1hEVEkwTURNeE1USXlNalV6TUZvd0lURWZNQjBHQTFVRUF3d1djR0Z5ZEc1bGNpQnphV2R1WVhSMWNtVWdZMlZ5ZERCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkFuRngwR1NKMklPZGZpcFdiMGMwZytBVThlbDh6QnRVS0kxdWRzT2kzN2thd1JRSFkzV29YaWRvRThIOHM1cVIySmo2ZkFKWVhOTURXY0NiditWMEJ1alV6QlJNQjBHQTFVZERnUVdCQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QWZCZ05WSFNNRUdEQVdnQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QVBCZ05WSFJNQkFmOEVCVEFEQVFIXC9NQW9HQ0NxR1NNNDlCQU1DQTBnQU1FVUNJUUNBRE9zZ0pZanRXVm9xNUZOSjc3U2JDeWtON1ZldUlKR2pXb3NBVUFNd1ZRSWdUTlVcL2ttc1wvN0cxVUx5Z01DRWVXemNiYTNrMVo4NEE4RmNlMXQzYUNGbGc9Il19..ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" "https://graph.facebook.com/1001200005002/notify_authorizations" \
  -d '{"notification":{"partner_merchant_id":"123e4567-e89b-12d3-a456-426614174000","container_id":"cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x","event_time":1582230020020,"type":"notify_authorizations"},"resource":{"partner_auth_id":"1234567890","auth_amount":{"currency":"USD","value":29508},"status":"SUCCEEDED","created_time":1582230019010,"metadata":[]},"idempotence_token":"ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"}'

次のデータをエンコードする事前リクエスト。

{
  "notification": {
    "partner_merchant_id": "123e4567-e89b-12d3-a456-426614174000",
    "container_id": "cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x",
    "event_time": 1582230020020,
    "type": "notify_authorizations"
  },
  "resource": {
    "partner_auth_id": "1234567890",
    "auth_amount": {
      "currency": "USD",
      "value": 29508
    },
    "status": "SUCCEEDED",
    "created_time": 1582230019010,
    "metadata": []
  },
  "idempotence_token": "ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"
}

事前リクエストの署名の例を次に示します。分かりやすくするために、Base64とJSONはデコードしてあります。

base64url(
 json({
   "x5c": [
     "MIIBhDCCASqgAwIBAgIBATAKBggqhkjOPQQDAjAhMR8wHQYDVQQDDBZwYXJ0bmVyIHNpZ25hdHVyZSBjZXJ0MB4XDTIwMDcxMzIyMjUzMFoXDTI0MDMxMTIyMjUzMFowITEfMB0GA1UEAwwWcGFydG5lciBzaWduYXR1cmUgY2VydDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAnFx0GSJ2IOdfipWb0c0g+AU8el8zBtUKI1udsOi37kawRQHY3WoXidoE8H8s5qR2Jj6fAJYXNMDWcCbv+V0BujUzBRMB0GA1UdDgQWBBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAfBgNVHSMEGDAWgBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQCADOsgJYjtWVoq5FNJ77SbCykN7VeuIJGjWosAUAMwVQIgTNU/kms/7G1ULygMCEeWzcba3k1Z84A8Fce1t3aCFlg="
   ],
   "alg": "ES256"
 })
) + // Protected Header
 "." +
 "" + // Payload is detached
 "." +
 "ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" // Signature

べき等

idempotence_tokenフィールドを使用して、ネットワーク障害やタイムアウト後にリクエストが再試行されたときに、リクエストが重複実行されないようにします。べき等トークンは、クライアントが生成する一意の値で、その生成方法はクライアントで決定します。たとえば、V4 UUIDを使用してべき等トークンを生成できます。

リクエストが正常に完了したとき、つまりAPI呼び出しが有効な結果を返したとき、応答データをべき等トークンを使用して保存します。成功したリクエストが以前のべき等トークンを使用して再試行されたとき、以前に保存された応答がどのコードも再実行されることなく返されます。

リクエストがエラーになった場合、保存される結果はありません。そのリクエストは同じべき等トークンを使用して再試行しできます。

同じべき等トークンを使用して2つのリクエストを同時に行った場合、1つのリクエストだけが応答データを返します。

べき等トークンは一時的なもので、エラーの際にAPI呼び出しを再試行するためだけに使用します。何回かリクエストを再試行した場合、直前の呼び出しとは異なる応答を受け取る場合があります。

リクエストパラメーターは無視されます。リクエストのコンテンツを何か変更した場合は、そのリクエスト用に新しいべき等トークンを作成してください。

バッチ照合

決済を処理したら、Meta Pay Webhooksを使うことによって、決済取引アクティビティをMetaに通知します。Webhooksを呼び出すと、決済取引アクティビティが顧客のFacebookアカウントのFacebook Payアクティビティページに可能な限り速やかに表示されます。

失敗したお知らせは、バッチ照合の間にMetaにキャプチャされ、顧客のFacebookアカウントに後から表示されます。

バッチ照合をサポートするため、その日にMetaに送ったお知らせを含むファイルを毎日アップロードします。成功したお知らせと失敗したお知らせの両方を含めます。Meta APIへのファイルのアップロードに関する詳細については、ファイルをFacebookにアップロードするをご覧ください。

エラーの処理

Meta Pay APIは標準的なグラフAPIエラー処理を使用します。

販売者の初期化と更新

サポートしている販売者のデータを初期化または更新するには、販売者Graph API /metapay_partner/merchantに対してPOSTリクエストを発行し、販売者パラメーターを指定します。

https://graph.facebook.com/metapay_partner/merchant

リクエストのパラメーター

応答

販売者APIにPOSTリクエストを行った後の200 OK応答は、POSTが正常に処理されたことを示しています。応答本文は、販売者のステータスが、ENABLEDとDISABLEDのどちらであるかを示します。空でないステータス修飾子は、追加情報を提供します。

成功した場合の一般的な応答は次のようになります。

{
    "status":"ENABLED",
    "status_modifiers":[]
}

一時的なスクリーニングを実施している状態の販売者の応答は次のようになります。

{
    "status":"DISABLED",
    "status_modifiers":["PENDING_SCREENING"]
}

設定される可能性があるステータス修飾子は次のようになります。

販売者を取得する

登録販売者のリストを取得するには、販売者Graph API /metapay_partner/merchantsに対してGETリクエストを発行します。

https://graph.facebook.com/metapay_partner/merchants

リクエストのパラメーター

URLのパラメーターとして、以下のリクエストの任意パラメーターがサポートされています。

応答

GET Merchants APIからの結果は、ページ分割されます。一般的な応答形式については、リンクされているページをご覧ください。data配列で返される各要素の形式は、販売者リクエストパラメーターの形式です。例:

curl -H "Authorization: OAuth $OAUTH" -X GET "https://graph.facebook.com/metapay_partner/merchants?partner_merchant_id=MERCHANT_TEST_1"
{
    "data": [
        {
            "partner_merchant_id": "MERCHANT_TEST_1",
            "merchant_status": "DISABLED",
            "display_name": "Test merchant 1",
            "business_uri": "https://facebook.com/",
            "icon_uri": "https://facebook.com/favicon.ico",
            "mcc_list": [7311],
            "support_email": "example@facebook.com",
            "support_phone": "+11234567890",
            "valid_origins": [
                "https://facebook.com/"
            ],
            "legal_structure": "COMPANY_TYPE_NOT_SPECIFIED",
            "status_modifiers":["BLOCKED"],
            "effective_merchant_status":"DISABLED"
        }
    ],
    "paging": {
        "cursors": {
            "before": "aaa...",
            "after": "bbb..."
        },
        "next": "https://graph.facebook.com/metapay_partner/merchants?limit=25&after=..."
    }
}

Webhooks

認証、キャプチャ、申し立て、決済、返金が生じた際には、必ずMetaのWebhooksを呼び出してMetaに決済取引アクティビティを知らせなければなりません。

200 OK応答は、Webhookが正常に処理されたことを示します。成功した場合、応答の本文でcontainer_idが返されます。

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

Webhook呼び出しが失敗した場合は、少なくとも72時間にわたって、間隔を徐々に空けながら呼び出しを3回以上再試行します。その後も呼び出しが失敗する場合、通知はバッチ照合で後でキャプチャされます。

Meta API Webhooksでモデル化されているリソースのエンティティ関連図を次に示します。黒い点が付いたプロパティは必須属性です。

通知

Webhookを呼び出すたびに、続くセクションで説明されているとおり、通知パラメーターをリクエスト本文に含め、通知タイプの詳細をリソースフィールドに含めます。通知の一般的な構造は次のとおりです。

{
  idempotence_token: '<your token>',
  notification:
  {
    ...
  },
  resource:
  {
    ...
  }
}

通知パラメーター

認証の通知

/<CONTAINER_ID>/notify_authorizationsに対してPOSTリクエストを発行し、決済取引の認証アクティビティをMetaに通知します。

https://graph.facebook.com/<CONTAINER_ID>/notify_authorizations

認証リソース

キャプチャの通知

/<CONTAINER_ID>/notify_capturesに対してPOSTリクエストを発行し、決済取引のキャプチャアクティビティをMetaに通知します。

https://graph.facebook.com/<CONTAINER_ID>/notify_captures

キャプチャのリソース

申し立ての通知

/<CONTAINER_ID>/notify_disputesに対してPOSTリクエストを発行し、決済取引の申し立てアクティビティをMetaに通知します。

https://graph.facebook.com/<CONTAINER_ID>/notify_disputes

申し立てのリソース

決済の通知

/<CONTAINER_ID>/notify_paymentsに対してPOSTリクエストを発行し、金銭の移動操作が伴わない決済アクティビティについてMetaに通知します。例えば、リスクチェックが不合格となった場合、ユーザーの支払いを処理しないことにするかもしれません。

https://graph.facebook.com/<CONTAINER_ID>/notify_payments

決済のリソース

返金の通知

/<CONTAINER_ID>/notify_refundsに対してPOSTリクエストを発行し、決済取引の返金アクティビティをMetaに通知します。

https://graph.facebook.com/<CONTAINER_ID>/notify_refunds

返金のリソース

合計額通知オブジェクト

合計額オブジェクトを使用して、認証、キャプチャ、申し立て、返金の通知に関する特定の通貨における金額を表します。

合計オブジェクト

エラー通知オブジェクト

認証、キャプチャ、決済、返金の処理時にエラーが発生した場合、resourceにerrorオブジェクトを含めてエラーに関する情報を提供します。

エラーオブジェクト