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, der zu Ihrer Engine passt, und nutzen Sie die Funktionen dann wie folgt:

window.JOGOS_SDK.payment;

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 Bestellung und tatsächlichem Zahlungseingang kann Zeit vergehen.
Abonnieren Sie die Erfolgs-Benachrichtigung; die Plattform informiert dann aktiv, sobald die Bestellung bezahlt ist und liefert die aktuellen Daten.

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.