Zahlungen Lite

Übersicht

Bei Zahlungen Lite handelt es sich um eine neue Methode, um In-App-Käufe direkt im App-Dashboard als products zu definieren und eine ID, einen Namen, eine Beschreibung, einen Preis, eine Währung und ein Bild zuzuweisen. Daraufhin wird im JavaScript-Aufruf anstelle der OG Object-URL, die für den standardmäßigen Zahlungsablauf erforderlich ist, die product ID übergeben, um den Zahlungsablauf zu starten. Dies optimiert die Erstellung und Änderung von Produkten, ohne dass hierfür ein Server-Push erforderlich wäre.

Erstellen von Produkten

Um ein Produkt zu erstellen, musst du im App-Dashboard zu Canvas-Zahlungen navigieren, um zum Abschnitt Produkte zu gelangen.

Um ein Produkt zu erstellen, klicke oben rechts auf den Button Neues Produkt erstellen. Gib im Dialog „Produktdetails“ Product ID, Title, Description und Price an, wähle eine Währung aus dem Dropdown-Menü aus und lade ein 50 mal 50 Pixel großes Bild hoch, das dein Produkt repräsentiert.

Product List API

Nachdem du die Produkte definiert hast, die in deinem Spiel zum Verkauf angeboten werden, musst du deinen In-Game-Store aufbauen. Hierüber können Spieler*innen das Produkt auswählen, das sie interessiert. Um sicherzustellen, dass du die richtigen Informationen für die anzubietenden Produkte verwendest, kannst du die Product List API zum Abrufen von Informationen zu den Produkten nutzen. Um eine Liste von Produkten abzurufen, musst du den folgenden Endpunkt aufrufen:

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

Mit folgenden Parametern:

Beispielaufruf und -antwort:

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

Aufrufen der Nutzungsoberfläche

Sobald der*die Nutzer*in ein Produkt ausgewählt hat, musst du ihn*sie dazu auffordern, den Kauf abzuschließen, indem du den Dialog „Zahlen“ aufrufst. Dies erreichst du über die ui-Funktion des FB-Objekts im JavaScript-SDK.

Um den Dialog „Zahlen“ aufzurufen, musst du als ersten Parameter ein JSON-Objekt mit folgenden Schlüsseln angeben:

Beispielcode zum Aufrufen des Dialogs:

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
);

Nachdem der Vorgang abgeschlossen wurde, kannst du das Ergebnis der Transaktion bestätigen, indem du eine Rückruffunktion als zweiten Parameter des Aufrufs angibst. Diese Funktion wird entweder mit einem Objekt, das Informationen zur Transaktion enthält, oder einem Fehlercode und folgender Nachricht aufgerufen:

Beispiel für erfolgreiche Antwort:

{
  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_...",
}

Beispieltransaktion mit Fehler:

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

Auflisten der Spieler*innenkäufe

Mit Zahlungen Lite kannst du die Käufe von Nutzer*innen zur Bestätigung bzw. zur Bestellverwaltung auflisten und verbrauchen. So hinderst du Spieler*innen daran, in deinem Spiel nicht nutzbare Produkte zu kaufen. Als Best Practice empfehlen wir, die Käufe des*der aktuellen Spieler*in zu überprüfen, nachdem das Spiel geladen wurde, um sicherzustellen, dass keine gekauften, aber noch nicht verbrauchten Produkte vorhanden sind.

Um die Käufe des*der aktuellen Nutzer*in aufzulisten, kannst du den /APP_ID/purchases-Endpunkt deiner Anwendung in Verbindung mit dem Nutzer*innen-Zugriffstoken verwenden. Dieser Aufruf gibt eine Liste aller gekauften, aber nicht verbrauchten Produkte des*der aktuellen Spieler*in zurück, einschließlich entsprechender Kaufinformationen.

Beispielsweise mit folgenden Aufrufen:

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
);

Beispielantwort:

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

Weitere Informationen zur von dieser Antwort zurückgegebenen „signed_request“ findest du in diesem Abschnitt.

Verbrauchen gekaufter Produkte

Nachdem ein Produkt gekauft wurde und du anhand der signierten Anfrage und der Entwickler*innen-Payload verifiziert hast, dass es sich um einen legitimen Kauf handelt, musst du dem*der Spieler*in den erworbenen Artikel oder die Währung im Spiel zukommen lassen. Wenn es sich hierbei um Produkte handelt, die verbraucht werden können (z. B. Währung, einmalig nutzbare Items usw.), musst du diesen Kauf als abgeschlossen markieren, um dem*der Nutzer*in den erneuten Kauf des gleichen Artikels zu ermöglichen. Produkte, die nicht verbraucht werden können (z.  B. zum Entsperren spezieller Funktionen, spezielle VIP-Programme usw.) dürfen nicht verbraucht werden, damit Nutzer*innen nicht versehentlich denselben Artikel mehrfach kaufen.

Um ein gekauftes Produkt zu verbrauchen, musst du das purchase_token verwenden, das du dem JavaScript-Aufruf oder der im vorigen Abschnitt erwähnten Liste von Spieler*innenkäufen entnehmen kannst. Um das Produkt zu verbrauchen, musst du folgenden Graph API-Endpunkt aufrufen:

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

Beispielsweise mit dem Facebook-JavaScript-SDK:

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
);

Beispiel für erfolgreiche Antwort:

{
  success: true,
}

Streitfälle

Streitfälle können mit großem zeitlichen Abstand zur ursprünglichen Zahlung erfolgen. Um einen Streitfall bearbeiten zu können, muss ein*e Entwickler*in über eine Streitfall-Serverkomponente verfügen, damit er*sie benachrichtigt werden kann, wenn ein Streitfallprozess von einer Partei initiiert wird. In Zahlungen Lite, einem serverlosen Zahlungssystem, werden alle Streitfälle automatisch rückerstattet und geschlossen. Einzelheiten zur Implementierung von Zahlungen und zur Abwicklung von Streitfällen mit einer Serverkomponente findest du unter Zahlungen und Streitfälle.