使用 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 开发者网站创建一个新应用程序。应用程序创建完毕后，您会获得该应用程序的应用编号和应用密钥。

每次向 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 响应，即表示 Webhooks 已被成功处理。若调用成功，响应正文将返回 container_id：

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

若 Webhooks 调用失败，请在至少 72 小时内，以递增退避的方式重新尝试调用至少 3 次。若调用仍旧失败，Meta 稍后可在批量对账期间捕获该通知。

实体关系图如下所示，其中各项是 Meta API Webhooks 中已用于模型的各类资源。黑点表示相关属性为必要项。

通知

每次调用 Webhooks 时，您都要在请求正文中添加通知参数，并在资源字段添加通知类型详情，正如后续小节所述。通知的一般结构如下所示：

{
  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 对象，以提供该错误的相关信息。

错误对象