使用 Meta Pay API

處理 Meta Pay 的付款作業時，您必須叫用 Meta Pay API 中的 Webhooks 來通知 Meta 授權和退款等付款交易活動。付款交易活動會顯示在顧客 Facebook 帳號的 訂單和付款頁面。

若要瞭解如何使用 Meta 的 API，請參閱圖形 API 總覽，並注意下面所述的 API 是相對於標準圖形 API 主機網址（https://graph.facebook.com）。如需更多一般資訊，請參閱 Meta Pay 整合總覽。

設置

您必須先完成下列操作，才能開始使用 Meta Pay API：

• 完成一般設置步驟
• 查看 Meta Pay 的付款處理程序

呼叫 Meta Pay API

進行一般設置步驟時，您需要在 Meta for Developers 入口網站中建立新的應用程式。建立應用程式後，您會取得該應用程式的應用程式編號和應用程式密鑰。

每次對 Meta Pay API 發出呼叫都需要提供這組應用程式編號和應用程式密鑰產生的應用程式存取權杖。請使用 Authorization 標頭傳送應用程式存取權杖，而不是 access_token 查詢參數。Meta Pay API 會拒絕透過用戶權杖發出的呼叫。

例如，您可以使用下列程式碼：

Authorization: OAuth <APP_ACCESS_TOKEN>

簽章

每個對 Meta Pay API 發出的 HTTP 要求都必須包含 FBPAY_SIGNATURE 要求標頭。此標頭的值為 JSON Web Signature（JWS）物件，內含 ES256 演算法、精簡序列化和分離的承載（根據 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 個要求，就只有一個要求會傳回回應資料。

冪等性權杖僅供暫時使用，且只能用來重新發出失敗的 API 呼叫。如果您過一段時間後才重新發出要求，則收到的回應可能會與先前呼叫的回應不同。

系統會忽略要求參數。如果您以任何方式變更要求的內容，請務必為該要求建立新的冪等性權杖。

批次對帳

處理付款作業時，您會使用 Meta Pay Webhooks 來通知 Meta 相關的付款交易活動。叫用 Webhooks 後，系統會盡快在顧客 Facebook 帳號的 Facebook Pay 動態頁面顯示該付款交易活動。

Meta 會在批次對帳期間擷取傳送失敗的通知，並於稍後顯示在顧客的 Facebook 帳號中。

為讓批次對帳作業順利進行，您應每天上傳相關檔案，其中含有當天傳送給 Meta 的通知，包括傳送成功和傳送失敗的通知。如需將檔案上傳至 Meta API 的詳細資訊，請參閱上傳檔案至 Facebook。

錯誤處理程序

Meta Pay API 採用標準圖形 API 錯誤處理程序。

初始化和更新商家

若要初始化或更新您支援之商家的資料，請對商家圖形 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"]
}

以下列出可能的狀態修飾詞。

取得商家

若要取得已註冊的商家清單，請向商家圖形 API /metapay_partner/merchants 發出 GET 要求。

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

要求參數

系統支援下列選用性要求參數做為網址參數：

回應

GET 商家 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 物件，藉此提供錯誤的相關資訊。

錯誤物件