So richten Sie die automatische Guthabenaufladung im SMM-Panel über die API ein

Was vor der Einrichtung der automatischen Aufladung vorzubereiten ist

Die automatische Aufladung verbindet das Guthaben des SMM-Panels mit einem Zahlungsdienst oder einem internen Billing. Der Dienst prüft den Restbetrag, erstellt eine Zahlung beim Erreichen eines festgelegten Schwellenwerts und schreibt Mittel erst nach bestätigter Zahlung gut. Für den Betrieb werden die API-Dokumentation des Panels, Zugang zur Zahlungs-API, separate Schlüssel für Test- und Produktivumgebung sowie ein Protokoll aller Vorgänge benötigt.

Prüfen Sie vor der Entwicklung, ob die API des Panels den Kontostand zurückgeben, eine Gutschriftsanfrage annehmen, die Aufladungshistorie anzeigen und eine externe Vorgangs-ID entgegennehmen kann. Wenn das Panel keine Gutschrift über die API unterstützt, kann die Automatisierung nur eine Anfrage erstellen oder eine Benachrichtigung an den Operator senden. Der Nachteil dieser Variante ist, dass das Geld trotzdem manuell eingezahlt werden muss.

Trennen Sie die Guthabenprüfung von der Zahlungsentscheidung

Die Prüfung des Restbetrags sollte besser als separate Aufgabe nach Zeitplan ausgeführt werden. Sie ruft das Guthaben ab, vergleicht es mit dem Schwellenwert und übergibt das Ergebnis an den Auflade-Handler. Erstellen Sie keine Zahlung direkt im Moment der API-Antwort, ohne aktuelle unvollständige Vorgänge zu prüfen: Parallele Aufgaben können dasselbe niedrige Guthaben sehen und mehrere Zahlungen erstellen.

Vor einer neuen Zahlung muss der Handler prüfen, ob es einen Vorgang mit dem Status „erstellt“, „wartet auf Zahlung“ oder „wird bestätigt“ gibt. Wenn ein solcher Eintrag existiert, wird kein neuer Versuch gestartet, bis der Abgleich abgeschlossen ist. Der Nachteil der sequenziellen Verarbeitung ist, dass bei einer langsamen Antwort der externen API die Aufladung später beginnen kann als bei mehreren parallelen Anfragen.

Wählen Sie den Schwellenwert und die Logik des Aufladebetrags

Der Guthaben-Schwellenwert wird mit einem Puffer für aktive Bestellungen, Warteschlangen bei Anbietern und Zahlungsverzögerungen gewählt. Für einen Kanal mit ungleichmäßiger Aktivität ist es riskant, sich nur am durchschnittlichen Verbrauch zu orientieren: Nach einem Stream, dem Start von Werbung oder einer Massenbestellung können die Abbuchungen stark steigen. Separat wird ein kritischer Wert festgelegt, bei dem eine Benachrichtigung eingeht, aber nicht zwingend automatisch eine Zahlung erstellt wird.

Der Aufladebetrag kann fest sein oder aus dem Verbrauch eines gewählten Zeitraums berechnet werden. Ein fester Betrag ist einfacher für Kontrolle und Abgleich. Sein Nachteil ist, dass in ruhigen Zeiten überschüssige Mittel auf dem Guthaben liegen können und bei starkem Anstieg der Bestellungen eine einzelne Aufladung möglicherweise nicht ausreicht. Ein berechneter Betrag ist flexibler, erfordert aber die Bereinigung der Statistik von anomalen Abbuchungen und Rückerstattungen.

Richten Sie finanzielle Beschränkungen getrennt vom Schwellenwert ein

Der Schwellenwert beantwortet nur die Frage, wann das System den Aufladevorgang starten darf. Die Beschränkungen beantworten eine andere Frage: Wie viele Mittel darf es abbuchen. Legen Sie den Höchstbetrag einer einzelnen Operation, ein Gesamtlimit für den Zeitraum und den zulässigen Restbetrag nach der Gutschrift fest. Diese Regeln werden vor der Erstellung der Zahlung geprüft, nicht nach deren Bezahlung.

Die automatische Aufladung darf keine Mittel ohne Limit pro Operation und Zeitraum abbuchen. Wenn der berechnete Betrag über dem zulässigen liegt, sollte der Vorgang besser in die manuelle Prüfung überführt und eine Benachrichtigung gesendet werden. Der Nachteil starrer Limits ist, dass bei schnellem Anstieg der Ausgaben das Guthaben aufgebraucht sein kann, bevor der verantwortliche Mitarbeiter die Erhöhung des Limits bestätigt.

Erstellen Sie separate Schlüssel und schützen Sie den Zugang

Verwenden Sie für das Skript zur automatischen Aufladung separate API-Schlüssel mit minimalen Rechten: Guthaben lesen, Zahlung erstellen, Status prüfen und bestätigten Vorgang gutschreiben. Zugang zu Benutzern, Diensteinstellungen, Bestellungen und Auszahlungen benötigt ein solcher Schlüssel nicht. Wenn der Dienst eine Beschränkung nach IP-Adressen unterstützt, erlauben Sie Anfragen nur vom Integrationsserver.

Schlüssel werden in Umgebungsvariablen oder einem geschützten Secret-Store gespeichert. Übertragen Sie sie nicht in Browser-Code, Logs, öffentliche Repositories oder Fehlermeldungen. Jeder Schlüssel muss einen Eigentümer und ein klares Verfahren zum Austausch haben. Der Nachteil häufiger Schlüsselrotation ist, dass die Aufladung stoppt, wenn das neue Secret nicht in allen Arbeitsprozessen aktualisiert wird.

Erstellen Sie eine Zahlung mit eindeutiger Kennung

Jeder Aufladung wird vor dem Aufruf der Zahlungs-API eine interne Kennung zugewiesen. Sie wird im Protokoll gespeichert und als Idempotenzschlüssel oder externe Vorgangsnummer übergeben. Bei einem Netzwerk-Timeout kann dieselbe Anfrage mit derselben Kennung wiederholt werden: Der Zahlungsdienst muss den bereits erstellten Vorgang zurückgeben und nicht das Geld erneut abbuchen.

Unten steht ein allgemeines Beispiel für eine Anfrage. Ersetzen Sie Feldnamen und Adressen durch die Werte aus der Dokumentation des jeweiligen Anbieters. In der Variablen PAYMENT_ID wird eine vorab erstellte eindeutige ID gespeichert, und CALLBACK_URL verweist auf den Webhook-Handler.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

Bestimmen Sie die Eindeutigkeit einer Zahlung nicht nur anhand des Betrags und der Erstellungszeit. Zwei gleiche Aufladungen können legitim sein, eine wiederholte Anfrage nach einem Fehler jedoch nicht. Der Nachteil einer externen ID in der eigenen Datenbank ist, dass sie zuverlässig gespeichert und nach der Stornierung eines Vorgangs nicht wiederverwendet werden darf.

Prüfen Sie das Guthaben und speichern Sie den Vorgangsstatus

Die Guthabenabfrage muss vor der Entscheidung über eine neue Aufladung und nach erfolgreicher Gutschrift erfolgen. Eine allgemeine Anfrage kann so aussehen: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". Speichern Sie in der Antwort nicht nur den Betrag, sondern auch den Prüfzeitpunkt, damit keine Entscheidung auf veralteten Daten getroffen wird.

Führen Sie für jeden Vorgang einen Eintrag mit interner ID, Zahlungs-ID beim Anbieter, Betrag, Währung, Erstellungszeit, Status, API-Antworten und Fehlerursache. Eine passende Statuskette: „erstellt“, „wartet auf Zahlung“, „bezahlt“, „wird gutgeschrieben“, „gutgeschrieben“, „storniert“, „erfordert Prüfung“.

Eine Gutschrift im Panel ist nur für eine bestätigte und noch nicht verarbeitete Zahlung zulässig. Überschreiben Sie Status nicht ohne Historie: Bei einem Streitfall muss ersichtlich sein, welche Anfrage gesendet wurde und warum der Vorgang geändert wurde. Der Nachteil eines ausführlichen Protokolls ist, dass es sensible Daten enthalten kann, weshalb der Zugang dazu beschränkt wird.

Nehmen Sie den Webhook entgegen und gleichen Sie den Zahlungsstatus ab

Die Seite einer erfolgreichen Zahlung und die Weiterleitung des Nutzers bestätigen nicht den Geldeingang. Eine Bestätigung ist der Webhook des Zahlungsdienstes oder eine erneute Statusprüfung über dessen API. Prüfen Sie beim Empfang eines Webhooks die Signatur, die Sendezeit, die Zahlungs-ID, die externe ID, den Betrag und die Währung. Erst danach überführen Sie den Vorgang in den Status der bestätigten Zahlung.

Nach der Prüfung des Webhooks ist es sinnvoll, den aktuellen Zahlungsstatus beim Anbieter abzufragen. Zum Beispiel: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Gleichen Sie den Status mit den Daten des Protokolls ab und senden Sie dann eine Gutschriftsanfrage an das SMM-Panel mit derselben internen ID.

Ein wiederholter Webhook darf keine zweite Gutschrift erstellen. Der Handler findet den Vorgang anhand der externen ID, sieht den Status „gutgeschrieben“ und gibt eine erfolgreiche Antwort ohne weitere Aktionen zurück. Der Nachteil von Webhooks ist, dass sie sich verzögern oder ausbleiben können, wenn der Handler nicht erreichbar war.

Behandeln Sie Timeouts, Retries und hängende Zahlungen

Senden Sie bei einem Timeout nach der Erstellung einer Zahlung keine neue Anfrage mit einer anderen ID. Suchen Sie zuerst den Vorgang anhand der internen Kennung oder wiederholen Sie die Anfrage mit demselben Idempotenzschlüssel. Wenn der Anbieter die ursprüngliche Anfrage angenommen hat, gibt er die bestehende Zahlung zurück. Das schützt bei einer Verbindungsunterbrechung vor doppelter Abbuchung.

Wenn der Webhook nicht innerhalb einer festgelegten Zeit eintrifft, fragt eine Hintergrundaufgabe den Zahlungsstatus über die API ab. Wiederholte Prüfungen erfolgen mit wachsender Pause und begrenzter Anzahl von Versuchen, um API und Protokoll nicht zu überlasten. Ein Vorgang, der lange im Wartezustand bleibt, wird in die manuelle Prüfung überführt und nicht ohne Abgleich als storniert betrachtet.

Bei Antworten über einen vorübergehenden Netzwerkfehler oder die Nichtverfügbarkeit der API sind Retries zulässig. Bei einer Zahlungsablehnung, einem falschen Betrag, einer ungültigen Webhook-Signatur oder einer Limitüberschreitung sollte die Anfrage nicht automatisch wiederholt werden. Der Nachteil von Retries ist, dass sie die Statuslogik verkomplizieren und bei einem massenhaften Ausfall beim Anbieter zusätzliche Last erzeugen können.

Schreiben Sie die bestätigte Zahlung dem SMM-Panel gut

Vor der Gutschrift prüft der Handler noch einmal: Der Betrag überschreitet nicht das Limit, die Währung stimmt überein, der Vorgang wurde nicht storniert und sein Status ist noch nicht „gutgeschrieben“. In der Anfrage werden der Betrag und die externe Zahlungs-ID übergeben. Wenn die API des Panels einen Idempotenzschlüssel unterstützt, verwenden Sie dieselbe interne Vorgangs-ID.

Allgemeine Form der Anfrage: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

Fragen Sie nach der Antwort des Panels das Guthaben erneut ab und speichern Sie das Ergebnis im Protokoll. Wenn das Geld beim Zahlungsdienst abgebucht wurde, die API des Panels aber einen Fehler zurückgegeben hat, erstellen Sie keine neue Zahlung. Der Vorgang bleibt im Status „erfordert Prüfung“ bis zur erneuten Gutschriftsanfrage oder manuellen Abgleich. Der Nachteil dieses vorsichtigen Schemas ist, dass das Guthaben möglicherweise vorübergehend nicht automatisch aufgeladen wird.

Fügen Sie Benachrichtigungen, einen Ausschalter und eine Startprüfung hinzu

Benachrichtigungen sind bei Abweichungen erforderlich: Das Guthaben ist unter den kritischen Wert gefallen, die Zahlung wurde abgelehnt, der Webhook wurde nicht empfangen, das Limit wurde überschritten, die API ist nicht verfügbar oder der Vorgang erfordert eine manuelle Prüfung. In der Nachricht genügt es, die interne ID, den Status und die Ursache anzugeben. Fügen Sie keine API-Schlüssel, Webhook-Signaturen und Zahlungsdaten hinzu.

Lassen Sie einen separaten Ausschalter für die automatische Aufladung, ohne die Integration zu entfernen. Er wird bei einem Anbieterwechsel, technischen Arbeiten, Verdacht auf einen Fehler oder einer starken Änderung der Ausgaben benötigt. Der Nachteil eines Ausschalters ist offensichtlich: Wenn er nach den Arbeiten nicht wieder eingeschaltet wird, kann das Guthaben während aktiver Bestellungen aufgebraucht werden.

Checkliste vor dem Einschalten der automatischen Aufladung

• Die Guthabenprüfung erstellt keine Zahlung, solange ein unvollständiger Vorgang existiert.
• Für jede Zahlung wird eine eindeutige interne ID und ein Idempotenzschlüssel erstellt.
• Limits für eine Operation und den gewählten Zeitraum sind eingerichtet.
• Webhooks werden nach Signatur, Betrag, Währung und Kennung geprüft.
• Bei fehlendem Webhook wird ein erneuter Statusabgleich über die API gestartet.
• Ein Timeout führt nicht zur Erstellung einer zweiten Zahlung vor der Prüfung der ersten.
• Die Gutschrift im Panel erfolgt einmalig und wird im Protokoll festgehalten.
• Der Testmodus wurde auf Erfolg, Ablehnung, doppelten Webhook und Nichtverfügbarkeit der API geprüft.