Before you can use the features described in this documentation to integrate with Meta Pay, you must request access from Meta. If you satisfy the prerequisites, email Meta-Pay-Partnerships@meta.com to request access.

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:

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

ParameterTypeDescriptionRequired

partner_merchant_id

String

A unique identifier for the merchant’s account with the payment partner.

Yes

business_uri

String

The URI to the merchant website that appears to customers in the Meta Pay interface. The URI must begin with http:// or https://.

Yes

display_name

String

The name of the merchant as it appears to customers in the Meta Pay interface.

Yes

mcc

int64

[Deprecated]

The merchant category code. Meta uses this categorize payment activity and ensure that payments meet our terms of service.


Note:

mcc or mcc_list must be provided.

No*

mcc_list

Array< int64>

The list of merchant category codes. Meta uses these categorize payment activity and ensure that payments meet our terms of service.


Note:

mcc or mcc_list must be provided. This is a preferred parameter over mcc.

No*

merchant_status

String

Whether the merchant is enabled or disabled with the payment partner. One of PENDING, ENABLED, or DISABLED. Pending has the same effect as disabled, but might indicate a temporarily disabled state.

Yes

icon_uri

URI

The URI to the merchant icon that appears to customers in the Meta Pay interface. The icon file format can be one of: png, jpeg.

No

support_email

String

An email address for customers to request a receipt or summary of the transaction.

No

support_phone

String

A phone number for customers to request support for a payment transaction. Format the phone number using one of the following formats: 16315551000, +1 631 555 1001, +1 (631) 555-1004, 1-631-555-1005.

No

valid_origins

Array< String>

A full list of valid security origin URIs for the merchant. This is used to ensure that payments are being initiated from expected web security origins.

No

pixel_id

String

A unique identifier for the merchant’s Meta Pixel. This is used to support Meta Checkout specific features in Ads Manager

No

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.

Status ModifierDescription

PENDING_SCREENING

The merchant is temporarily blocked from using Meta Pay pending the result of compliance screening. Typically screening completes in 24 hours. Query the merchant API to verify status.

INVALID_ICON

The icon_uri is not acceptable. The file format was incorrect, the file exceeded the size limit, or the URI could not be retrieved. This status modifier does not prevent the merchant from using Meta Pay.

INTEGRITY_FLAG

One or more of the merchant properties triggered an integrity flag. The merchant will be disabled.

BLOCKED

The merchant is permanently blocked from using Meta Pay.

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:

ParameterTypeDescriptionRequired

partner_merchant_id

String

Comma seperated partner merchant ids to apply as filtering criteria

No

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

PropertyTypeDescriptionRequired

merchant_id

String

Your unique identifier for the merchant's account. You can use the following characters: [a-zA-Z0-9_-].

Yes

type

String

The type of notification. Valid values are: notify_authorizations, notify_captures, notify_disputes, notify_payments, and notify_refunds, and should match the webhook that you are invoking. This is used by batch reconciliation.

Yes

event_time

Int64

The UNIX timestamp in milliseconds.

Yes

container_id

String

A unique identifier for the container structure.

Yes

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

PropertyTypeDescriptionRequired

partner_auth_id

String

Your unique identifier for the authorization or charge. You can use the following characters: [a-zA-Z0-9_-].

Yes

auth_amount

A notification amount object

The amount that is authorized. Currently, only USD is supported for currency.

Yes

status

String

The status of the authorization. One of: PENDING, SUCCEEDED, FAILED, CANCELED.

Yes

created_time

Int64

The UNIX timestamp in milliseconds of when the authorization was attempted.

Yes

description

String

A description of the payment transaction.

No

statement_descriptor

String

A description of the payment transaction that appears to the customer, for example on their credit card statement.

No

error

A notification error object.

Details of an error if one occurs. Valid values for code are INVALID_PAYMENT_METHOD, PROCESSING_FAILURE, EXPIRED, and OTHER.

No

metadata

Object {String : String}

An array of key-value pairs that provide addition information about the authorization.

No

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

PropertyTypeDescriptionRequired

partner_capture_id

String

Your unique identifier for the capture. You can use the following characters: [a-zA-Z0-9_-].

Yes

partner_auth_id

String

Your previously-created identifier for the authorization or charge that corresponds to this capture.

No

capture_amount

A notification amount object

The amount that is captured. Currently, only USD is supported for currency.

Yes

status

String

The status of the capture. One of: PENDING, SUCCEEDED, FAILED.

Yes

created_time

Int64

The UNIX timestamp in milliseconds of when the capture was attempted.

Yes

note

String

A note from the merchant describing the capture.

No

error

A notification error object.

Details of an error if one occurs. Valid values for code are PROCESSING_FAILURE, DECLINED, and OTHER.

No

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

PropertyTypeDescriptionRequired

partner_dispute_id

String

Your unique identifier for the dispute. You can use the following characters: [a-zA-Z0-9_-].

Yes

created_time

Int64

The UNIX timestamp in milliseconds of when the dispute was created.

Yes

dispute_amount

A notification amount object

The amount that is disputed. Currently, only USD is supported for currency.

Yes

reason

String

The reason for the dispute. One of: BANK_CANNOT_PROCESS, CREDIT_NOT_PROCESSED, CUSTOMER_INITIATED, DEBIT_NOT_AUTHORIZED, DUPLICATE, FRAUDULENT, GENERAL, INCORRECT_ACCOUNT_DETAILS, INSUFFICIENT_FUNDS, PRODUCT_UNACCEPTABLE, SUBSCRIPTION_CANCELED, OTHER_UNRECOGNIZED, PRODUCT_NOT_RECEIVED, INCORRECT_AMOUNT, PAYMENT_BY_OTHER_MEANS, PROBLEM_WITH_REMITTANCE.

Yes

status

String

The status of the dispute. One of: RESOLVED_BUYER_FAVOR, REVERSED_SELLER_FAVOR, RETRIEVAL_EVIDENCE_REQUESTED, RETRIEVAL_UNDER_REVIEW, RETRIEVAL_CLOSED, BUYER_REFUNDED, CHARGEBACK_EVIDENCE_REQUESTED, CHARGEBACK_UNDER_REVIEW.

Yes

partner_payment_id

String

Your previously-created identifier for the payment that corresponds to this dispute.

No

partner_capture_ids

Array< String>

The identifiers for the captures that correspond to the dispute. This property is optional.

No

description

String

A description of the dispute.

No

metadata

Object {String : String}

An array of key-value pairs that provide addition information about the dispute.

No

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

PropertyTypeDescriptionRequired

partner_payment_id

String

Your unique identifier for the payment. You can use the following characters: [a-zA-Z0-9_-].

Yes

status

String

The status of the payment. One of: PENDING, SUCCEEDED, FAILED, CANCELED.

Yes

created_time

Int64

The UNIX timestamp in milliseconds of when the payment was attempted.

Yes

metadata

Object {String : String}

An array of key-value pairs that provide addition information about the payment.

No

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

PropertyTypeDescriptionRequired

partner_refund_id

String

Your unique identifier for the refund. You can use the following characters: [a-zA-Z0-9_-].

Yes

created_time

Int64

The UNIX timestamp in milliseconds of when the refund was created.

Yes

refund_amount

A notification amount object

The amount that is refunded. Currently, only USD is supported for currency.

Yes

status

String

The status of the refund. One of: PENDING, SUCCEEDED, FAILED, CANCELED.

Yes

partner_capture_id

String

Your previously-created identifier for the capture that corresponds to this refund.

No

description

String

A description of the refund.

No

statement_descriptor

String

A description of the refund that appears to the customer, for example on their credit card statement.

No

error

A notification error object.

Details of an error if one occurs. Valid values for code are PROCESSING_FAILURE, DECLINED, and OTHER.

No

metadata

Object {String : String}

An array of key-value pairs that provide addition information about the refund.

No

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

PropertyTypeDescription

currency

String

The 3-letter currency code from the ISO 4217 standard for the the monetary amount. For the list of currency codes, see ISO 4217. Currently, only USD is supported for currency.

value

Int

The value of the monetary amount expressed in the smallest unit of currency. For example, if currency is USD, express a value of $19.99 in cents as 1999.

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

PropertyTypeDescription

code

String

A Meta-specific error code. Valid values depend on the notification type and are documented in the preceding sections.

partner_code

String

Your code for the error.

partner_error

String

Your description of the error.