Utilisation de l’API Meta Pay

Lorsque vous traitez des paiements pour Meta Pay, vous devez notifier à Meta les activités liées aux transactions, telles que les autorisations et les remboursements, en appelant les webhooks de l’API Meta Pay. Les activités liées aux transactions apparaissent sur la page Commandes et paiements dans le compte Facebook des clients et clientes.

Pour apprendre utiliser les API de Meta, consultez la page Vue d’ensemble de l’API Graph et notez que les API décrites ci-dessous sont relatives à l’URL hôte standard de l’API Graph (https://graph.facebook.com). Pour des informations plus générales, voir Vue d’ensemble de l’intégration de Meta Pay.

Intégration

Nous vous recommandons d’effectuer les démarches suivantes avant de commencer à utiliser les API Meta Pay :

• Suivez les étapes générales d’intégration.
• Consultez l’article Traitement des paiements dans Meta Pay.

Appel des API Meta Pay

Au cours des étapes générales d’intégration, vous créez une application sur le portail Meta for Developers. Une fois votre application créée, vous obtenez un ID d’application et une clé secrète pour votre application.

Chacun de vos appels d’API Meta Pay doit inclure un token d’accès d’application dérivé de l’ID et de la clé secrète de votre application. Pour transmettre le token d’accès d’application, utilisez l’en-tête Authorization, et non un paramètre de requête access_token. Les API Meta Pay refusent les appels associés à des tokens d’accès d’utilisateur·ice.

Par exemple, utilisez le code suivant :

Authorization: OAuth <APP_ACCESS_TOKEN>

Signature

Chaque requête HTTP adressée aux API Meta Pay doit inclure un en-tête de requête FBPAY-SIGNATURE. La valeur de cet en-tête est constituée d’un objet JWS (JSON Web Signature) avec l’algorithme ES256, d’une sérialisation compacte et d’une charge utile détachée (selon la norme https://tools.ietf.org/html/rfc7515#appendix-F). La valeur de la charge utile est le corps de la requête HTTP POST. La clé de la signature JWS doit être identifiée avec l’en-tête x5c qui doit contenir un certificat relié à la racine de confiance du partenaire. Le certificat racine du partenaire est partagé avec Meta dans le cadre du processus d’intégration (appelé certificat de signature de l’API Meta Pay).

Exemple de requête avec une 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"}'

La requête précédente encode les données suivantes :

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

Voici la signature associée à la requête précédente, décodée Base64 et JSON pour plus de clarté :

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

Idempotence

Le champ idempotence_token est utilisé pour éviter que des requêtes soient exécutées deux fois lorsqu’une défaillance du réseau ou une expiration du délai d’attente entraîne une nouvelle tentative de requête. Le jeton d’idempotence est une valeur unique générée par le client, et ce dernier décide de quelle manière générer ce jeton. Par exemple, vous pouvez utiliser un UUID V4 pour générer un jeton d’idempotence.

Lorsqu’une requête réussit ou qu’un appel d’API renvoie des résultats valides, les données de la réponse sont enregistrées avec le jeton d’idempotence. Si une requête ayant réussi fait l’objet d’une nouvelle tentative avec un jeton d’idempotence précédemment utilisé, la réponse précédemment enregistrée est renvoyée sans qu’aucun code ne soit exécuté.

Lorsqu’une requête génère une erreur, aucun résultat n’est enregistré. Vous pouvez renouveler la requête en utilisant le même jeton d’idempotence.

Si vous effectuez deux requêtes simultanées avec le même jeton d’idempotence, seule l’une d’elles renvoie les données de la réponse.

Les jetons d’idempotence sont destinés à une utilisation temporaire et uniquement pour les appels d’API qui sont renouvelés en cas d’échec. Si vous renouvelez une requête après un certain temps, vous risquez de recevoir une réponse différente de l’appel précédent.

Les paramètres de requête sont ignorés. Si vous modifiez le contenu d’une requête de quelque manière que ce soit, créez un nouveau jeton d’idempotence pour la requête en question.

Rapprochement par lots

Lorsque vous traitez des paiements, vous notifiez à Meta les activités liées aux transactions à l’aide des webhooks Meta Pay. Les appels de webhooks permettent d’afficher l’activité de transaction de paiement concernée dès que possible sur la page Activité Facebook Pay dans le compte Facebook du client ou de la cliente.

Les notifications qui échouent sont capturées par Meta lors du rapprochement par lots et apparaissent plus tard dans le compte Facebook du client ou de la cliente.

Pour faciliter le rapprochement par lots, importez chaque jour un fichier contenant les notifications que vous avez envoyées à Meta ce jour-là. Incluez dans ce fichier les notifications qui ont réussi et celles qui ont échoué. Pour plus d’informations sur l’importation de fichiers dans l’API Meta, voir Importer des fichiers dans Facebook.

Gestion des erreurs

Les API Meta Pay utilisent la gestion standard des erreurs de l’API Graph.

Initialisation et mise à jour des vendeurs

Pour initialiser et mettre à jour les données relatives à un vendeur, envoyez une requête POST au point de terminaison /metapay_partner/merchant de l’API Graph et spécifiez les paramètres du vendeur.

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

Paramètres de la requête

Réponse

Lorsque vous envoyez une requête POST à l’API Merchant, une réponse 200 OK indique que la requête POST a bien été traitée. Le corps de la réponse indique le statut du vendeur, ENABLED ou DISABLED. Les modificateurs de statut non vides donnent des informations complémentaires.

Une réponse de réussite ressemble généralement à ceci :

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

Une réponse relative à un vendeur qui fait l’objet d’un contrôle temporaire se présente comme suit :

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

Voici les différents modificateurs de statut possibles :

Obtention de la liste des vendeurs

Pour récupérer une liste des vendeurs inscrits, envoyez une requête GET à l’API Graph Merchant /metapay_partner/merchants.

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

Paramètres de la requête

Les paramètres de requête facultatifs suivants sont pris en charge comme paramètres d’URL :

Réponse

Les résultats de la requête GET envoyée à l’API Merchant sont paginés. Consultez la page en lien pour connaître le format général des réponses. Chaque élément renvoyé dans le tableau data est au format des paramètres de requête de vendeurs. Exemple :

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

Vous devez notifier les activités liées aux transactions de paiement à Meta en appelant les webhooks de Meta, dès qu’une autorisation, une capture, un litige, un paiement ou un remboursement se produit.

Une réponse 200 OK indique que le webhook a bien été traité. En cas de réussite, le corps de la réponse comprend le container_id :

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

En cas d’échec, essayez d’appeler le webhook au moins trois fois pendant au moins soixante-douze heures avec un délai de rappel incrémental. Si l’appel échoue malgré tout, la notification peut être capturée plus tard, lors du rapprochement par lots.

Voici un diagramme de relation entre entités représentant les ressources modélisées dans les webhooks de l’API Meta. Les propriétés associées à un point noir correspondent aux attributs obligatoires.

Notification

Chaque fois que vous appelez un webhook, incluez un paramètre de notification dans le corps de la requête et les détails concernant le type de notification dans le champ de la ressource, comme décrit dans les sections qui suivent. La structure générale de la notification est la suivante :

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

Paramètre de notification

Notifier des autorisations

Envoyez une requête POST à /<CONTAINER_ID>/notify_authorizations pour notifier à Meta une activité d’autorisation pour une transaction de paiement.

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

Ressource d’autorisation

Notifier des captures

Envoyez une requête POST à /<CONTAINER_ID>/notify_captures pour notifier à Meta une activité de capture pour une transaction de paiement.

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

Ressource de capture

Notifier des litiges

Envoyez une requête POST à /<CONTAINER_ID>/notify_disputes pour notifier à Meta une activité de litige pour une transaction de paiement.

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

Ressource de litige

Notifier des paiements

Envoyez une requête POST à /<CONTAINER_ID>/notify_payments pour notifier à Meta une activité de paiement qui ne se rapporte pas à des opérations de transfert d’argent. Par exemple, vous pouvez décider de ne pas traiter le paiement d’un utilisateur ou d’une utilisatrice lorsque la vérification des risques échoue.

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

Ressource de paiement

Notifier des remboursements

Envoyez une requête POST à /<CONTAINER_ID>/notify_refunds pour notifier à Meta une activité de remboursement pour une transaction de paiement.

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

Ressource de remboursement

Objet amount de la notification

Utilisez un objet amount pour représenter une valeur monétaire dans une devise spécifique pour les notifications d’autorisation, de capture, de litige et de remboursement.

Objet amount

Objet error de la notification

Si une erreur se produit lorsque vous traitez une autorisation, une capture, un paiement ou un remboursement, incluez un objet error dans la resource pour fournir des informations concernant l’erreur.

Objet error