# Zahlungen

Das Zahlungsmodul stellt Funktionen für den Kauf von In-Game-Artikeln sowie für Kauf-die-Vollversion-Transaktionen bereit.  
Lesen Sie den Abschnitt auf der Seite [`JOGOS_SDK-Einführung`](./introduction.md), der zu Ihrer Engine passt, und nutzen Sie die Funktionen dann wie folgt:

::: tabs key:engine

== HTML5

```javascript
window.JOGOS_SDK.payment;

== Cocos

JOGOS_SDK.payment;

== Unity

JogosSDK.Goods

:::

In-App-Käufe

Schritt 1: Artikel-ID anlegen

• Erstellen Sie im Entwickler-Dashboard auf der Seite „Information / Purchase“ einen Artikel.
• Beachten Sie: Innerhalb eines Spiels darf keine Artikel-ID doppelt vergeben werden.

Schritt 2: Bestellung auslösen

• Wenn ein Spieler einen Artikel kaufen möchte, rufen Sie über den Kauf-Button diese Schnittstelle auf, um das Jogos-Zahlungsfenster zu öffnen.
• Übergeben Sie die Artikel-ID; bei erfolgreichem Öffnen erhalten Sie eine Bestellnummer, über die Sie später Details abrufen können.
• goodsId entspricht der im Dashboard angelegten Artikel-ID.

// Liefert bei Erfolg die Bestellnummer
let orderNo = await window.JOGOS_SDK.payment.buyGoods(goodsId: string);

Schritt 3: Auf Zahlung des Nutzers warten

Vom Client aus Bezahl-Completion abonnieren

Zwischen der Bestellung durch den Spieler und dem erfolgreichen Zahlungsvorgang kann eine längere Zeit vergehen. Entwickler können diese Schnittstelle nutzen, um Benachrichtigungen über erfolgreiche Zahlungen zu abonnieren (Aufruf nach Initialisierung). Nach erfolgreicher Zahlung informiert die Plattform den Entwickler per Callback mit aktualisierten Bestellinformationen

window.JOGOS_SDK.payment.subscribeOrderPaid(callbackFn: (order: PaymentOrder) => void);

Schritt 4: Artikel ausliefern und Plattform informieren

Auslieferung über den Client (Offline-Spiele)

Nach erfolgreichem Zahlungsempfang gibt der Client die Belohnung aus und ruft diese Schnittstelle auf, um der Plattform den Abschluss mitzuteilen.

Hinweis

• Falls Ihr Spiel keinen eigenen Server besitzt, sollten Sie nach Zahlungserhalt über den Client diese Schnittstelle aufrufen und Jogos mitteilen, dass der Artikel ausgeliefert wurde.
• Verarbeiten Sie je nach Rückgabewert die Belohnung oder zeigen Sie eine Fehlerbeschreibung an.
• Rufen Sie nach der Auslieferung die Cloud-Save-Synchronisation auf, um die Spielerdaten zu sichern.

await window.JOGOS_SDK.payment.deliverGoods(orderNo: string);

Alternativ: Integration über Game-Server

Serverseitige APIs finden Sie auf der Seite: Server-Integration-Schnittstellen.

---

Weitere Schnittstellen

Tipps zur Optimierung der Zahlungsabwicklung

• Die Client-Subscription subscribeOrderPaid kann aufgrund von Netzwerkproblemen u. ä. nicht zu 100 % garantiert werden. Nutzen Sie die Bestell-Detail-API, um den aktuellen Status abzurufen.
• In Offline-Spielen mit Löschfunktion für Saves entscheiden Sie selbst, ob frühere Käufe erneut belohnt werden. Die Bestell-List-API liefert alle Käufe des Spielers.
• Verarbeiten Sie die Bestellung anhand des Feldes status.

Bestellinformationen

Details zu einer Bestellung über die Bestellnummer abrufen. Struktur:

// Zahlungsbestellung
export interface PaymentOrder {
  // Spiel-ID
  gameId: number;
  // Spielname
  gameName: string;
  // Nutzer-ID
  userId: number;
  // Bestellnummer
  orderNo: string;
  // Artikel-ID
  productId: string;
  // Artikelname
  productName: string;
  // Währung
  currency: string;
  // Land
  country: string;
  // Rabatt
  discount: number;
  // Jogos-Coins (Punkte)
  calorcoin: number;
  // Gezahlter Betrag
  paid: number;
  // Zahlungskanal
  channel: string;
  // Zahlungsart
  paymentType: string;
  // Zahlungs-ID
  paymentNo: string;
  // Bereits ausgeliefert?
  deliverGoods: boolean;
  // Status: pending = offen, fail = fehlgeschlagen, cancel = storniert, expire = abgelaufen, success = erfolgreich, refunding = Rückerstattung läuft, refunded = rückerstattet, refund-fail = Rückerstattung fehlgeschlagen
  status: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded' | 'refund-fail';
  // Erstellungszeitpunkt
  createTime: String;
  // Rückerstattungs-ID
  refundNo: String;
  // Rückerstattungs-Grund
  refundDescription: String;
  // Zeitpunkt der Rückerstattungs-Anfrage
  refundTime: String;
  // Zeitpunkt der erfolgreichen Rückerstattung
  refundedTime: String;
}

Bestelldaten abrufen

// Liefert bei Erfolg die Bestelldaten
let order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo: string);

Bestellliste abrufen

Über diese Schnittstelle können Sie alle Bestellungen eines bestimmten Status abrufen. Die zurückgegebene Liste enthält Objekte mit derselben Struktur wie die Detail-Abfrage.

// Liefert bei Erfolg die Bestellliste
let orderList = await window.JOGOS_SDK.payment.getOrderList(
  status?: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded',
  pageNo?: number,  // Seitennummer, Standard: 1
  pageSize?: number // Einträge pro Seite, Standard: 20
);

---

Kauf-die-Vollversion-Spiele

1. Setzen Sie Ihr Spiel im Dashboard auf „Game Pricing“ (Buy-out) und geben Sie einen Preis an.
2. Erstellen Sie zwei Builds: Demo und Vollversion

• Demo: Entfernen Sie nicht zugängliche Level, Assets, Modelle, Texturen, Musik usw. – nur spielbarer Demo-Inhalt bleibt. Diesen Build separat hochladen.
• Vollversion: Enthält den gesamten Spielinhalt.

3. Kauf-Button in der Demo platzieren:

• Nach Demo-Ende (z. B. letztes Level von Kapitel 1) zeigen Sie einen „Vollversion kaufen“-Bildschirm mit Kauf-Button:
• Button ruft buyOut auf und öffnet das Jogos-Zahlungsfenster.
• Nach erfolgreicher Zahlung wechselt Jogos automatisch zur Vollversion; weitere Aktionen Ihrerseits entfallen.
• Halten Sie Versionsnummern von Demo und Vollversion synchron – Saves werden automatisch übertragen.
• Nach Zahlung erhalten Sie eine Bestellnummer, über die Sie Details abrufen können.

// Liefert bei Erfolg die Bestellnummer
let orderNo = await window.JOGOS_SDK.payment.buyOut();

*Wichtiger Hinweis*

Sowohl Demo als auch Vollversion müssen in der ersten Szene initialisiert werden. Warten Sie auf den Initialisierungs-Callback, bevor Sie auch nur eine Zeile Spiel-Code ausführen. Jogos prüft beim Start, ob der Nutzer das Spiel gekauft hat – andernfalls kann er nicht weiterspielen.
Dies ist ein effektiver Schutz gegen Piraterie.

```