Payments Lite

Présentation

Payments Lite est un nouveau moyen de définir les achats intégrés à votre jeu en tant que products, directement depuis l’Espace App, en leur attribuant un ID, un nom, une description, un prix, une devise et une image. Le product ID est ensuite transmis dans l’appel JavaScript pour lancer le flux de paiement plutôt que d’utiliser l’URL OG Object requise par le flux de paiement normal. Cela permet de simplifier le flux de création et de modification des produits sans avoir recours à un push de serveur.

Création de produits

Pour créer un produit, vous devez accéder à Paiements Canvas dans l’Espace App afin d’afficher la sous-section Produits.

Cliquez ensuite sur le bouton Créer un nouveau produit en haut à droite. Dans la boîte de dialogue Détails du produit, saisissez les Product ID, Title, Description et Price, puis sélectionnez une devise dans le menu déroulant et importez une image de 50 × 50 pixels qui représentera votre produit.

API Product List

Après avoir défini les produits disponibles à la vente dans votre jeu, vous pouvez créer votre magasin intégré au jeu. Les joueurs et les joueuses pourront ainsi sélectionner le produit qu’ils ou elles souhaitent acheter. Afin de vous assurer que vous utilisez les bonnes informations sur les produits que vous souhaitez vendre, vous pouvez utiliser l’API Product List pour récupérer les informations concernant ces produits. Pour obtenir une liste des produits, vous devez appeler le point de terminaison suivant :

GET https://graph.facebook.com/APP_ID/products

Avec les paramètres suivants :

Exemple d’appel et de réponse :

FB.api(
  '/app/products', 
  'get', 
  function(response) {
    console.log(response);
  }
);

FB.API(
  "app/products",
  HttpMethod.GET,
  this.productCallback // callback that receives a IGraphResult
);

{
  "data": [
    {
      "title": "100 coins lite package",
      "product_id": "payments_lite_test_01",
      "product_type": "managed",
      "description": "Package of 100 coins to test Payments Lite",
      "price": "$1.00",
      "price_amount_cents": 100,
      "price_currency_code": "USD"
    },
    {
      "title": "Friend Smash!",
      "product_id": "480369938658210_premium",
      "product_type": "managed",
      "description": "One time purchase to play game",
      "price": "$0.01",
      "price_amount_cents": 1,
      "price_currency_code": "USD"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUlg1cXRqcnVad05taFRVRlZAZAU2tQdWNSd0FKRDh1TTJMdGd3azVTZA3ZAZAOFgzcXZAaZAlQ1N1VMMmRmZAXpUNG9KX2tsSWhYVlB6Yko2cEotUXZAiRGgzQkFKc0lJLUQzVlJxbHVPampZAS19SWEQ4",
      "after": "QVFIUmRiSGltU1BKQnRqWTRxNkd1WktUTHFKMmxvaEwtV2dSYUtpeDJxQnN0Ri1mZAnF0TG1Ub3oyWnphSExqZAU5qQzNNZAmFrejVnSTlaRVVGMXdSSlNsNE13"
    }
  }
}

Invocation de l’UI

Une fois que le joueur ou la joueuse a sélectionné un produit, vous devez lui demander de valider l’achat en invoquant la boîte de dialogue Paiement. Pour ce faire, utilisez la fonction ui de l’objet FB du SDK JavaScript de Facebook.

Pour invoquer la boîte de dialogue Paiement, vous devez fournir un objet JSON comme premier paramètre avec les clés suivantes :

Exemple de code d’invocation de la boîte de dialogue :

FB.ui(
  {
    method: 'pay',
    action: 'purchaseiap',
    product_id: 'com.fb.friendsmash.coins.10',
    developer_payload: 'this_is_a_test_payload'
  },
  response => (console.log(response)) // Callback function
);

FB.PayWithProductId(
  "com.fb.friendsmash.coins.10",
  "purchaseiap",
  1,
  null, null, null, null, null,
  this.payCallback  // Callback function that receives an IPayResult
);

Au terme du flux, vous pouvez vérifier le résultat de la transaction en fournissant une fonction de rappel comme second paramètre de l’appel d’invocation. Cette fonction est appelée avec soit un objet contenant des informations sur la transaction, soit un code d’erreur et un message :

Exemple de réponse en cas de réussite :

{
  app_id: 241431489326925,
  developer_payload: "this_is_a_test_payload",
  payment_id: 860496004080598,
  product_id: "com.fb.friendsmash.coins.10",
  purchase_time: 1473719771,
  purchase_token: "10157567446205226",
  signed_request: "M3fQFj6MlK7WJi597QgCvMlMLh7fl_...",
}

Exemple de transaction comportant une erreur :

{
  error_code: 1383010, 
  error_message: "User canceled the order."
}

Ajout à une liste des achats du joueur ou de la joueuse

Payments Lite permet de répertorier les achats et de les consommer, ce qui correspond à une forme de vérification et de gestion des achats. Cela signifie que les joueurs et les joueuses ne peuvent pas acheter de produits non consommables dans votre jeu. Nous vous recommandons vivement de contrôler les achats du joueur ou de la joueuse actuel·le après le chargement du jeu, afin de vérifier qu’aucun achat n’est en attente de consommation.

Pour dresser la liste des achats du joueur ou de la joueuse actuel·le, vous pouvez utiliser le point de terminaison /APP_ID/purchases de votre application, associé à un token d’accès utilisateur·ice. Cet appel renvoie une liste de tous les achats non consommés pour le joueur ou la joueuse actuel·le, ainsi que les informations relatives à ces achats.

Utilisez, par exemple, les appels suivants :

FB.api(
  '/app/purchases',
  'get',
  {access_token: 'ACCESS_TOKEN'},      // user access token
   payload => {        // callback function
     console.log('purchases payload:');
     console.log(payload);
   }
);

FB.API(
  "/app/purchases?access_token=YOUR_ACCESS_TOKEN",
  HttpMethod.GET,
  this.purchasesCallback // callback that receives a IGraphResult
);

Exemple de réponse :

{
  data: [
    {
      app_id: 241431489326925,
      developer_payload: "this_is_a_test_payload",
      payment_id: 860496004080598,
      product_id: "com.fb.friendsmash.coin",
      purchase_time: 1473719771,
      purchase_token: "10157567446205226",
      signed_request: "M3fQFj6MlK7WJi597QgCvMlMLh7fl_...",
    },
    {
      ...
    }
  ],
  paging: {
    cursors: {
      after: "M3fQFj6MlK7WJi597QgCvMlMLh7fl...",
      before: "M3fQFj6MlK7WJi597QgCvMlMLh7...",
    }
  }
}

Pour plus d’informations sur la signed_request renvoyée dans cette réponse, reportez-vous à cette section.

Consommation d’un achat

Une fois qu’un produit a été acheté et que vous avez vérifié sa légitimité à l’aide de la requête signée et de votre charge utile de développeur ou de développeuse, vous devez attribuer l’article ou la devise acheté·e au joueur ou à la joueuse concerné·e. À ce stade, si le produit acheté est consommable (devise ou article à usage unique, par exemple), vous devez marquer cet achat comme consommé pour permettre à l’utilisateur·ice d’acheter une autre copie de ce même article. Les produits non consommables (déverrouillage de fonctionnalités spéciales ou programmes VIP spéciaux, par exemple) ne doivent pas être consommés pour éviter que les utilisateur·ices achètent plusieurs fois le même article.

Pour consommer un achat, vous devez utiliser le purchase_token fourni dans le rappel JavaScript ou dans la liste des achats du joueur ou de la joueuse mentionnée à la section précédente. Pour consommer l’achat, vous devez appeler le point de terminaison de l’API Graph suivant :

POST	https://graph.facebook.com/PURCHASE_TOKEN/consume

Par exemple, à l’aide du SDK Facebook pour JavaScript :

FB.api(
  '/' + PURCHASE_TOKEN + '/consume',    // Replace the PURCHASE_TOKEN
  'post',
  {access_token: access_token},         // Replace with a user access token
  result => {
    console.log('consuming product', productId, 'with purchase token', purchaseToken);
    console.log('Result:');
    console.log(result);
  }
);

FB.API(
  "/YOUR_PURCHASE_TOKEN/consume?access_token=YOUR_ACCESS_TOKEN",
  HttpMethod.POST,
  this.consumeCallback // callback that receives a IGraphResult
);

Exemple de réponse en cas de réussite :

{
  success: true,
}

Litiges

Les litiges peuvent survenir bien après la réalisation du paiement initial. La présence d’un composant serveur dédié au traitement des litiges est donc requise pour informer le développeur ou la développeuse du lancement d’une procédure de litige par un joueur ou une joueuse. Dans Payments Lite, qui est un système de paiement sans serveur, tous les litiges sont remboursés et clôturés automatiquement. Pour plus d’informations sur la manière d’implémenter les paiements et de traiter les litiges à l’aide d’un composant serveur, consultez les pages Réception de paiements et Litiges.