Using the Meta Pay API

When you process payments for Meta Pay you must notify Meta of payment transaction activity, such as authorizations and refunds, by invoking webhooks in the Meta Pay API. Payment transaction activity appears in the Orders and payments page of a customer's Facebook account.

To learn how to use Meta's APIs, see Overview of the Graph API and note that the APIs described below are relative to the standard Graph API host URL (https://graph.facebook.com). For more general information, see Overview of Meta Pay Integration.

Onboarding

Before you can start using the Meta Pay APIs you should complete the following:

• Complete the general onboarding steps
• Review Payment Processing in Meta Pay

Calling the Meta Pay APIs

As part of the general onboarding steps you create a new application in the Meta for Developers Portal. After you create your application you get an app ID and app secret for your app.

Each call that you make to a Meta Pay API requires an app access token derived from the app ID and app secret. Send the app access token by using the Authorization header not an access_token query parameter. The Meta Pay APIs reject calls with user tokens.

For example, use the following code:

Authorization: OAuth <APP_ACCESS_TOKEN>

Signature

Every HTTP request to the Meta Pay APIs must include a FBPAY_SIGNATURE request header. The value of this header is a JSON Web Signature (JWS) object with the ES256 algorithm, compact serialization, and a detached payload (according to https://tools.ietf.org/html/rfc7515#appendix-F). The payload value is the HTTP POST request body. The JWS signature key must be identified with the x5c header, which must contain a certificate that chains to the partner’s trusted root. The partner's root certificate is shared with Meta as part of the onboarding process (referred to as the Meta Pay API signature certificate).

Example of a request with a signature

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"}'

The preceding request encodes the following data:

{
  "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"
}

The following is the signature from the preceding request, Base64 and JSON decoded for clarity:

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

Idempotency

The idempotence_token field is used to prevent duplicate execution of requests when requests are retried after network failures or timeouts. The idempotence token is a unique value generated by the client and the client decides how to generate this token. For example, you can use V4 UUID to generate an idempotence token.

When a request completes successfully, or a call to the API returns valid results, the response data is saved with the idempotence token. When a successful request is retried with a previously-used idempotency token, the previously saved response is returned without rerunning any code.

When a request results in an error, no results are saved. You can retry the request and use the same idempotency token.

If you make 2 requests concurrently with the same idempotency token, only one returns response data.

Idempotency tokens are intended to be temporary and only used for retrying API calls in case of failures. If you retry a request after some time, you might receive a different response than the previous call.

Request parameters are ignored. If you change request content in any way, create a new idempotence token for the request.

Batch Reconciliation

When you process payments you notify Meta of payment transaction activity by using the Meta Pay webhooks. By invoking webhooks the payment transaction activity appears in the Facebook Pay Activity page of a customer's Facebook account as soon as possible.

Notifications that fail are captured by Meta during batch reconciliation and appear in the customer's Facebook account later.

To support batch reconciliation, each day upload a file that contains the notifications that you sent to Meta that day. Include both notifications that succeeded and notifications that failed. For details about uploading a file to the Meta API, see Upload Files to Facebook.

Error Handling

The Meta Pay APIs use the standard Graph API error handling.

Initializing and Updating Merchants

To initialize or update the data for a merchant that you support, make a POST request to the merchant Graph API /metapay_partner/merchant and specify the merchant parameters.

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

Request parameters

Response

After you make a POST request to the merchant API a 200 OK response indicates that the POST has been processed successfully. The response body indicates the status of the merchant, either ENABLED or DISABLED. Non-empty status modifiers provide addional information.

A common successful response looks like the following:

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

A response for a merchant that is undergoing temporary screening looks like the following:

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

The following are the possible status modifiers.

Get Merchants

To fetch a list of registered merchants, make a GET request to the merchant Graph API /metapay_partner/merchants.

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

Request parameters

The following optional request params are supported as URL parameters:

Response

The results from GET Merchants API are paginated. See the linked page for general response format. Each element returned in the data array will be in the format of Merchant request params. Example:

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

You must notify Meta of payment transaction activity by invoking Meta's webhooks whenever any authorization, capture, dispute, payment, or refund occurs.

A 200 OK response indicates that the webhook has been processed successfully. A successful response body will return the container_id:

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

If a webhook invocation fails, retry the invocation at least three times for at least seventy two hours with incremental backoff. If the invocation still fails, the notification can be captured later during batch reconciliation.

The following is an entity relationship diagram for the resources modeled in the Meta API webhooks. Properties with black dots denote mandatory attributes.

Notification

Each time you invoke a webhook, include a notification parameter in the request body and details for the notification type in the resource field, as described in the sections that follow. The general structure for the notification is the following:

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

Notification Parameter

Notify Authorizations

Make a POST request to /<CONTAINER_ID>/notify_authorizations to notify Meta about authorization activity for a payment transaction.

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

Authorization resource

Notify Captures

Make a POST request to /<CONTAINER_ID>/notify_captures to notify Meta about capture activity for a payment transaction.

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

Capture resource

Notify Disputes

Make a POST request to /<CONTAINER_ID>/notify_disputes to notify Meta about dispute activity for a payment transaction.

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

Dispute resource

Notify Payments

Make a POST request to /<CONTAINER_ID>/notify_payments to notify Meta about payment activity that does not relate to money movement operations. E.g. you may decide to not process a user's payment when it fails risk checks.

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

Payment resource

Notify Refunds

Make a POST request to /<CONTAINER_ID>/notify_refunds to notify Meta about refund activity for a payment transaction.

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

Refund resource

Notification Amount Object

Use an amount object to represent a monetary value in a specific currency for notifications for authorizations, captures, disputes, and refunds.

Amount object

Notification Error Object

If an error occurs when you process an authorization, capture, payment, or refund, include an error object in the resource to provide information about the error.

Error object