Como usar a API do Meta Pay

Ao processar pagamentos com o Meta Pay, é necessário notificar a Meta sobre transações de pagamento (como autorizações e reembolsos). Para isso, é necessário invocar webhooks na API do Meta Pay. As transações de pagamento são exibidas na página Pedidos e pagamentos da conta do Facebook de um cliente.

Para aprender a usar as APIs da Meta, consulte Visão geral – Graph API. As APIs descritas abaixo seguem o padrão de URL de hospedagem (https://graph.facebook.com). Para ver mais informações, consulte Visão geral da integração do Facebook Pay.

Integração

Antes de começar a usar as APIs do Meta Pay:

• Conclua as etapas de integração.
• Analise o documento sobre processamento de pagamentos com o Meta Pay.

Chamadas às APIs do Meta Pay

As etapas gerais de integração incluem a criação de um app no portal Meta for Developers. Depois de criá-lo, você obtém um ID e uma chave secreta do app.

Para fazer chamadas a uma API do Meta Pay, é necessário ter um token de acesso do app derivado do ID e da chave secreta. Envie o token de acesso do app com o cabeçalho Authorization, e não com um parâmetro de consulta access_token. As APIs do Meta Pay rejeitam chamadas com tokens de usuário.

Por exemplo, use o código a seguir:

Authorization: OAuth <APP_ACCESS_TOKEN>

Assinatura

Todas as solicitações HTTP às APIs do Meta Pay precisam incluir um cabeçalho de solicitação FBPAY_SIGNATURE. O valor desse cabeçalho é um objeto de assinatura da web JSON (JWS, pelas iniciais em inglês) com o algoritmo ES256, além de serialização compacta e uma carga separada (conforme https://tools.ietf.org/html/rfc7515#appendix-F). O valor da carga é o corpo da solicitação HTTP POST. A chave da assinatura JWS deve ser identificada com o cabeçalho x5c, que precisa conter um certificado anexado à raiz confiável do parceiro. Esse certificado é compartilhado com a Meta como parte do processo de integração (referido como certificado de assinatura da API do Meta Pay).

Exemplo de uma solicitação com assinatura

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

A solicitação anterior codifica os dados a seguir:

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

Confira a seguir a assinatura da solicitação anterior decodificada em Base64 e JSON para fins de clareza:

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

Idempotência

O campo idempotence_token é usado para evitar a execução duplicada de solicitações quando há novas tentativas de solicitação devido a falhas ou a tempos-limite de rede. O token de idempotência é um valor único gerado pelo cliente, que é quem decide como gerar esse token. Por exemplo, é possível usar a versão 4 de um identificador único universal (UUID, pelas iniciais em inglês) para gerar um token de idempotência.

Quando uma solicitação é concluída sem falhas ou uma chamada à API retorna resultados válidos, os dados de resposta são salvos com o token de idempotência. Já quando uma nova tentativa de solicitação bem-sucedida é feita usando um token de idempotência utilizado previamente, a resposta anterior salva é retornada sem que o código seja executado novamente.

Quando uma solicitação terminar em erro, nenhum resultado será salvo. Você pode fazer uma nova tentativa de solicitação e usar o mesmo token de idempotência.

Se você fizer duas solicitações simultaneamente usando o mesmo token de idempotência, apenas uma delas retornará dados de resposta.

Os tokens de idempotência são para uso temporário e somente em novas tentativas de chamadas de API por conta de falhas. Caso você tente fazer uma solicitação novamente após algum tempo, poderá receber uma resposta diferente à obtida na chamada anterior.

Os parâmetros de solicitação são ignorados. Se você alterar o conteúdo da solicitação de qualquer forma, será necessário criar outro token de idempotência para a solicitação.

Reconciliação de lote

Ao processar pagamentos, você notifica a Meta sobre a atividade de transações por meio dos webhooks do Meta Pay. Ao acionar webhooks, a atividade de transações de pagamento será exibida assim que possível na página Atividade do Facebook Pay da conta do Facebook de um cliente.

As notificações que resultam em falha são capturadas pela Meta durante a reconciliação de lote e aparecerão posteriormente na conta do Facebook do cliente.

Para auxiliar a reconciliação de lote, carregue diariamente um arquivo com as notificações que você enviou à Meta no dia correspondente. Inclua tanto as notificações bem-sucedidas quanto as que resultaram em falha. Para mais detalhes sobre como carregar um arquivo na API da Meta, consulte API de Carregamento Retomável.

Solução de erros

As APIs do Meta Pay usam o procedimento padrão de solução de erros da Graph API.

Como inicializar e atualizar comerciantes

Para inicializar ou atualizar os dados de um comerciante atendido por você, faça uma solicitação POST a /metapay_partner/merchant da Graph API de comerciante e especifique os parâmetros de comerciante.

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

Parâmetros de solicitação

Resposta

Se você receber uma resposta 200 OK depois de fazer uma solicitação POST à API do comerciante, isso significa que o processamento de POST ocorreu com sucesso. O corpo da resposta indica o status do comerciante, seja ENABLED ou DISABLED. Além disso, modificadores de status não vazios fornecem informações adicionais.

Confira uma resposta comum em caso de sucesso:

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

A seguir, veja a resposta para um comerciante que está passando por uma triagem temporária:

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

Listamos os modificadores de status possíveis a seguir.

Obter comerciantes

Para buscar a lista de comerciantes registrados, faça uma solicitação GET para /metapay_partner/merchants da Graph API de comerciante.

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

Parâmetros de solicitação

Veja os parâmetros opcionais de solicitação aceitos como parâmetros de URL:

Resposta

Os resultados de solicitações GET à API de comerciantes são paginados. Acesse o guia vinculado para ver o formato de resposta geral. Os elementos retornados na matriz data estarão no formato de parâmetros de comerciante. Exemplo:

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

É necessário notificar a Meta sobre as transações de pagamento. Para isso, invoque webhooks da Meta sempre que houver autorizações, capturas, contestações, pagamentos ou reembolsos.

Uma resposta 200 OK indica que o webhook foi processado com sucesso. A resposta bem-sucedida incluirá o container_id:

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

Se a invocação do webhook falhar, tente novamente no mínimo três vezes por pelo menos 72 horas com backoff incremental. Caso ainda não seja possível fazer o acionamento, a notificação poderá ser capturada mais tarde, durante a reconciliação de lote.

Confira a seguir um diagrama do relacionamento entre entidades dos recursos modelados nos webhooks da API da Meta. As propriedades com pontos pretos são atributos obrigatórios.

Notificação

Toda vez que você acionar um webhook, inclua um parâmetro de notificação no corpo da solicitação, bem como detalhes sobre o tipo de notificação no campo de recurso, conforme descrito nas seções a seguir. A estrutura geral da notificação é a seguinte:

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

Parâmetro de notificação

Notificar autorizações

Faça uma solicitação POST a /<CONTAINER_ID>/notify_authorizations para notificar a Meta sobre a autorização de uma transação de pagamento.

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

Recurso de autorização

Notificar capturas

Faça uma solicitação POST a /<CONTAINER_ID>/notify_captures para notificar a Meta sobre a captura de uma transação de pagamento.

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

Recurso de captura

Notificar contestações

Faça uma solicitação POST a /<CONTAINER_ID>/notify_disputes para notificar a Meta sobre a contestação de uma transação de pagamento.

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

Recurso de contestação

Notificar pagamentos

Faça uma solicitação POST a /<CONTAINER_ID>/notify_payments para notificar a Meta sobre atividades de pagamento que não têm relação com operações de movimentação de dinheiro. Por exemplo, você pode decidir não processar o pagamento de um usuário cuja verificação de risco tenha falhado.

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

Recurso de pagamento

Notificar reembolsos

Faça uma solicitação POST a /<CONTAINER_ID>/notify_captures para notificar a Meta sobre o reembolso de uma transação de pagamento.

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

Recurso de reembolso

Objeto de quantia de notificação

Use um objeto de quantia para representar um valor monetário em determinada moeda nas notificações sobre autorizações, capturas, contestações e reembolsos.

Objeto de quantia

Objeto de erro de notificação

Em caso de erro durante o processamento de autorizações, capturas, pagamentos ou reembolsos, inclua um objeto error em resource para fornecer informações sobre esse erro.

Objeto de erro