使用 Meta Pay API

處理 Meta Pay 的付款事務時，您必須在 Meta Pay API 中觸發 Webhooks 以向 Meta 通知有關付款交易動態，例如授權和退款。付款交易動態顯示在顧客 Facebook 帳戶的 訂單和付款頁面。

如要了解如何使用 Meta 的 API，請參閱 Graph API 概覽。請留意，下方所述的 API 與標準的 Graph 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 Pay API 簽署憑證），與 Meta 分享。

包含簽署的要求範例

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 使用標準的 Graph 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

要求參數

以下選用要求參數支援用作網址參數：

回應

從 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 回應，即表示 Webhooks 已被成功處理。成功的回應正文會傳回 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 物件，以提供該錯誤的相關資訊。

錯誤物件