Использование Meta Pay API

При обработке платежей для Meta Pay необходимо уведомлять Meta о действиях платежных транзакций, таких как авторизация и возвраты, используя webhooks в API Meta Pay. Информация о платежных транзакциях отображается на странице Заказы и платежи клиентского аккаунта Facebook.

Чтобы узнать, как использовать API Meta, см. Обзор API Graph и обратите внимание, что описанные ниже API относятся к стандартному адресу хоста API Graph (https://graph.facebook.com). Общую информацию см. в статье Обзор интеграции Meta Pay.

Подключение

Прежде чем начать использовать API Meta Pay, необходимо:

• выполнить общие шаги по подключению;
• проверить обработку платежей в Meta Pay.

Вызов Meta Pay API

В рамках общих шагов по подключению вы должны создать новое приложение на портале Meta для разработчиков. После этого вы получите ID приложения и секрет приложения для вашего приложения.

Для каждого вызова Meta Pay API требуется маркер доступа приложения, который является производным от ID секрета приложения. Отправьте маркер доступа приложения, используя заголовок Authorization, а не параметр запроса access_token. API Meta Pay отклоняют вызовы с пользовательскими маркерами.

Например, используйте следующий код:

Authorization: OAuth <APP_ACCESS_TOKEN>

Подпись

Каждый HTTP-запрос к API Meta Pay должен содержать заголовок запроса FBPAY_SIGNATURE. Значение этого заголовка — объект веб-подписи JSON (JWS) с алгоритмом ES256, компактной сериализацией и отдельными полезными данными (в соответствии с документом https://tools.ietf.org/html/rfc7515#appendix-F). Значение полезных данных — это тело запроса HTTP POST. Ключ подписи JWS должен быть идентифицирован с помощью заголовка x5c, который должен содержать сертификат, связанный с доверенным корнем партнера. Корневой сертификат партнера передается Meta в рамках процесса регистрации (именуется сертификатом подписи API Meta Pay).

Пример запроса с подписью

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 используется для предотвращения повторного выполнения запросов, когда запросы повторяются после сетевых сбоев или тайм-аутов. Маркер идемпотентности — это уникальное значение, генерируемое клиентом, и клиент решает, как его генерировать. Например, это можно делать с использованием UUID версии 4.

Когда запрос выполняется успешно или вызов API возвращает допустимые результаты, данные ответа сохраняются с маркером идемпотентности. Когда успешный запрос повторяется с ранее использованным маркером идемпотентности, ранее сохраненный ответ возвращается без повторного выполнения какого-либо кода.

Когда запрос приводит к ошибке, результаты не сохраняются. Вы можете повторить запрос и использовать тот же маркер идемпотентности.

Если одновременно отправить два запроса с одним и тем же маркером идемпотентности, только один из них вернет данные ответа.

Маркеры идемпотентности предназначены для временного использования и применяются только для повторных вызовов API в случае сбоев. Если вы повторите запрос через некоторое время, то можете получить другой ответ, чем для предыдущего вызова.

Параметры запроса игнорируются. Если вы каким-либо образом измените содержимое запроса, создайте для него новый маркер идемпотентности.

Пакетная сверка

При обработке платежей вы уведомляете Meta о действиях платежных транзакций с помощью Webhooks Meta Pay. При вызове Webhooks действие платежной транзакции максимально быстро появляется на странице Действия Facebook Pay клиентского аккаунта Facebook.

Неполученные уведомления регистрируются Meta во время пакетной сверки и позже появляются в клиентском аккаунте Facebook.

Для поддержки пакетной сверки каждый день загружайте файл, содержащий уведомления, которые вы отправили в Meta в этот день. Он должен содержать как полученные, так и не полученные уведомления. Информацию о загрузке файла в API Meta см. в статье Загрузка файлов на Facebook.

Обработка ошибок

API Meta Pay используют стандартную обработку ошибок API Graph.

Инициализация и обновление продавцов

Чтобы инициализировать или обновить данные для поддерживаемого продавца, отправьте запрос POST к API Graph продавца /metapay_partner/merchant и укажите параметры продавца.

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

Параметры запроса

Ответ

После отправки запроса POST к API продавца ответ 200 OK означает, что запрос POST успешно обработан. Тело ответа указывает на статус продавца (ENABLED или DISABLED). Непустые модификаторы статуса предоставляют дополнительную информацию.

Стандартный успешный ответ выглядит следующим образом:

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

Ответ для продавца, который временно проходит проверку, выглядит следующим образом:

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

Ниже приведены возможные модификаторы статуса.

Помощь продавцам

Чтобы получить список зарегистрированных продавцов, отправьте запрос GET к API Graph продавца /metapay_partner/merchants.

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

Параметры запроса

В качестве параметров URL поддерживаются следующие необязательные параметры запроса:

Ответ

Результаты из 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 не удался, повторите попытку не менее трех раз в течение как минимум семидесяти двух часов с дополнительным замедлением. Если вызов все равно завершится сбоем, уведомление может быть зарегистрировано позже в ходе пакетной сверки.

Ниже представлена диаграмма сущностей и связей для ресурсов, смоделированных с помощью Webhooks API Meta. Свойства с черными точками обозначают обязательные свойства.

Уведомление

При каждом вызове Webhook добавляйте параметр уведомления в тело запроса и сведения о типе уведомления в поле resource, как описано в следующих разделах. Общая структура уведомления такова:

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

Параметр уведомления

Уведомления об авторизации

Отправьте запрос POST к /<CONTAINER_ID>/notify_authorizations, чтобы уведомить Meta о действии авторизации для платежной транзакции.

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

Ресурс авторизации

Уведомления о подтверждении

Отправьте запрос POST к /<CONTAINER_ID>/notify_captures, чтобы уведомить Meta о действии подтверждения для платежной транзакции.

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

Ресурс подтверждения

Уведомления о споре

Отправьте запрос POST к /<CONTAINER_ID>/notify_disputes, чтобы уведомить Meta о действии спора для платежной транзакции.

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

Ресурс спора

Уведомления о платеже

Отправьте запрос POST к /<CONTAINER_ID>/notify_payments, чтобы уведомить Meta о платежной активности, которая не связана с операциями по перемещению денег. Например, вы можете принять решение не обрабатывать платеж пользователя, если он не прошел проверку на наличие рисков.

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

Ресурс платежа

Уведомления о возврате

Отправьте запрос POST к /<CONTAINER_ID>/notify_refunds, чтобы уведомить Meta о действии возврата для платежной транзакции.

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

Ресурс возврата

Объект суммы уведомления

Используйте объект суммы для представления денежного значения в определенной валюте в уведомлениях об авторизации, подтверждении, споре и возврате.

Объект суммы

Объект ошибки уведомления

Если при обработке авторизации, подтверждения, платежа или возврата происходит ошибка, добавьте объект error в resource, чтобы предоставить информацию о ней.

Объект ошибки