Hoe u automatische balansaanvulling in het SMM-paneel via API instelt

Wat u moet voorbereiden voordat u automatische balansaanvulling instelt

Automatische balansaanvulling koppelt het saldo van het SMM-paneel aan een betaaldienst of interne billing. De dienst controleert het resterende saldo, maakt een betaling aan wanneer een ingestelde drempel wordt bereikt en schrijft middelen pas bij na bevestiging van de betaling. Voor de werking zijn de API-documentatie van het paneel, toegang tot de betalings-API, afzonderlijke sleutels voor de test- en productieomgeving en een logboek van alle operaties nodig.

Controleer vóór de ontwikkeling of de API van het paneel het saldo kan teruggeven, een verzoek om bijschrijving kan aannemen, de geschiedenis van aanvullingen kan tonen en een externe operatie-identificatie kan aannemen. Als het paneel geen bijschrijving via API ondersteunt, kan de automatisering alleen een aanvraag aanmaken of een melding naar de operator sturen. Het nadeel van deze variant is dat het geld alsnog handmatig moet worden gestort.

Scheid de balanscontrole van de beslissing over de betaling

De controle van het resterende saldo kunt u het beste als afzonderlijke taak volgens een schema starten. Deze haalt het saldo op, vergelijkt het met de drempel en geeft het resultaat door aan de aanvulhandler. Maak geen betaling direct op het moment van het API-antwoord zonder de huidige onvoltooide operaties te controleren: parallelle taken kunnen hetzelfde lage saldo zien en meerdere betalingen aanmaken.

Vóór een nieuwe betaling moet de handler controleren of er geen operatie is met de status "aangemaakt", "wacht op betaling" of "wordt bevestigd". Als zo'n record bestaat, wordt een nieuwe poging niet gestart tot de afstemming is afgerond. Het nadeel van sequentiële verwerking is dat bij een langzaam antwoord van de externe API de aanvulling later kan beginnen dan bij meerdere parallelle verzoeken.

Kies de drempel en de logica van het aanvulbedrag

De balansdrempel wordt gekozen met een marge voor actieve bestellingen, de wachtrij bij leveranciers en betalingsvertragingen. Voor een kanaal met ongelijkmatige activiteit is het riskant om alleen op het gemiddelde verbruik te vertrouwen: na een stream, het starten van advertenties of een massale bestelling kunnen afschrijvingen sterk stijgen. Apart wordt een kritiek niveau ingesteld waarbij een melding binnenkomt, maar niet noodzakelijk automatisch een betaling wordt aangemaakt.

Het aanvulbedrag kan vast zijn of worden berekend op basis van het verbruik over een gekozen periode. Een vast bedrag is eenvoudiger voor controle en afstemming. Het nadeel is dat in een rustige periode overtollige middelen op de balans kunnen staan, terwijl bij een sterke groei van bestellingen één aanvulling mogelijk niet voldoende is. Een berekend bedrag is flexibeler, maar vereist opschoning van de statistieken van afwijkende afschrijvingen en terugbetalingen.

Stel financiële beperkingen apart van de drempel in

De drempel beantwoordt alleen de vraag wanneer het systeem het aanvulproces mag starten. Beperkingen beantwoorden een andere vraag: hoeveel middelen het mag afschrijven. Stel een maximumbedrag per operatie, een totale limiet per periode en een toegestaan saldo na bijschrijving in. Deze regels worden gecontroleerd vóór het aanmaken van de betaling, niet na de betaling ervan.

Automatische balansaanvulling mag geen middelen afschrijven zonder limiet per operatie en periode. Als het berekende bedrag hoger is dan toegestaan, kunt u de operatie het beste naar handmatige controle sturen en een melding versturen. Het nadeel van strikte limieten is dat bij een snelle groei van de kosten het saldo kan opraken voordat de verantwoordelijke medewerker de verhoging van de limiet bevestigt.

Maak afzonderlijke sleutels aan en beveilig de toegang

Gebruik voor het script voor automatische balansaanvulling afzonderlijke API-sleutels met minimale rechten: saldo lezen, betaling aanmaken, status controleren en een bevestigde operatie bijschrijven. Toegang tot gebruikers, dienstinstellingen, bestellingen en het opnemen van middelen is voor zo'n sleutel niet nodig. Als de dienst beperking op IP-adressen ondersteunt, sta verzoeken dan alleen toe vanaf de integratieserver.

Sleutels worden opgeslagen in omgevingsvariabelen of een beveiligde secrets-opslag. Geef ze niet door aan browsercode, logs, openbare repositories en foutmeldingen. Elke sleutel moet een eigenaar en een duidelijke vervangingsprocedure hebben. Het nadeel van frequente sleutelrotatie is dat de aanvulling stopt als het nieuwe geheim niet in alle werkprocessen wordt bijgewerkt.

Maak een betaling aan met een unieke identificatie

Aan elke aanvulling wordt een interne identificatie toegekend vóór het verzoek aan de betalings-API. Deze wordt in het logboek opgeslagen en doorgegeven als idempotentiesleutel of extern operatienummer. Bij een netwerktime-out kan hetzelfde verzoek met dezelfde identificatie worden herhaald: de betaaldienst moet de al aangemaakte operatie teruggeven en niet opnieuw geld afschrijven.

Hieronder staat een algemeen voorbeeld van een verzoek. Vervang veldnamen en adressen door de waarden uit de documentatie van de specifieke provider. In de variabele PAYMENT_ID staat een vooraf aangemaakte unieke ID, en CALLBACK_URL verwijst naar de 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"}'

Bepaal de uniciteit van een betaling niet alleen op basis van het bedrag en het tijdstip van aanmaken. Twee identieke aanvullingen kunnen legitiem zijn, maar een herhaald verzoek na een storing niet. Het nadeel van een externe ID in uw eigen database is dat deze betrouwbaar moet worden opgeslagen en niet opnieuw mag worden gebruikt na annulering van de operatie.

Controleer het saldo en sla de status van de operatie op

Het saldo moet worden opgevraagd vóór de beslissing over een nieuwe aanvulling en na een succesvolle bijschrijving. Een algemeen verzoek kan er zo uitzien: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". Sla in het antwoord niet alleen het bedrag op, maar ook het controletijdstip, zodat u geen beslissing neemt op basis van verouderde gegevens.

Houd voor elke operatie een record bij met de interne ID, de betalings-ID bij de provider, het bedrag, de valuta, het tijdstip van aanmaken, de status, de API-antwoorden en de foutoorzaak. Een passende reeks toestanden: "aangemaakt", "wacht op betaling", "betaald", "wordt bijgeschreven", "bijgeschreven", "geannuleerd", "vereist controle".

Bijschrijving in het paneel is alleen toegestaan voor een bevestigde en nog niet verwerkte betaling. Overschrijf statussen niet zonder geschiedenis: bij een geschil moet zichtbaar zijn welk verzoek is verzonden en waarom de operatie is gewijzigd. Het nadeel van een gedetailleerd logboek is dat het gevoelige gegevens kan bevatten, daarom wordt de toegang ertoe beperkt.

Ontvang de webhook en controleer de betalingsstatus

De pagina voor een geslaagde betaling en de redirect van de gebruiker bevestigen de ontvangst van het geld niet. Bevestiging is een webhook van de betaaldienst of een herhaalde statuscontrole via de API ervan. Controleer bij ontvangst van een webhook de handtekening, het verzendtijdstip, de betalings-ID, de externe ID, het bedrag en de valuta. Zet de operatie pas daarna in de status bevestigde betaling.

Na controle van de webhook is het nuttig om de actuele betalingsstatus bij de provider op te vragen. Bijvoorbeeld: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Vergelijk de status met de gegevens in het logboek en stuur vervolgens een verzoek om bijschrijving naar het SMM-paneel met dezelfde interne ID.

Een herhaalde webhook mag geen tweede bijschrijving aanmaken. De handler vindt de operatie op basis van de externe ID, ziet de status "bijgeschreven" en geeft een succesvol antwoord terug zonder nieuwe acties. Het nadeel van webhooks is dat ze vertraagd kunnen zijn of niet aankomen als de handler niet beschikbaar was.

Verwerk time-outs, retries en vastgelopen betalingen

Stuur bij een time-out na het aanmaken van een betaling geen nieuw verzoek met een andere ID. Zoek eerst de operatie op basis van de interne identificatie of herhaal het verzoek met dezelfde idempotentiesleutel. Als de provider het oorspronkelijke verzoek heeft aangenomen, geeft deze de bestaande betaling terug. Dit beschermt tegen dubbele afschrijving bij een verbroken verbinding.

Als de webhook niet binnen de ingestelde tijd is aangekomen, vraagt een achtergrondtaak de betalingsstatus op via de API. Herhaalde controles worden uitgevoerd met een toenemende pauze en een beperkt aantal pogingen, om de API en het logboek niet te overbelasten. Een operatie die lang in afwachting blijft, wordt naar handmatige controle gestuurd en niet zonder afstemming als geannuleerd beschouwd.

Bij antwoorden over een tijdelijke netwerkfout of onbeschikbaarheid van de API zijn retries toegestaan. Bij weigering van de betaling, een onjuist bedrag, een ongeldige webhook-handtekening of overschrijding van de limiet moet het verzoek niet automatisch worden herhaald. Het nadeel van retries is dat ze de statuslogica complexer maken en extra belasting kunnen veroorzaken bij een massale storing bij de provider.

Schrijf een bevestigde betaling bij in het SMM-paneel

Vóór de bijschrijving controleert de handler nogmaals: het bedrag overschrijdt de limiet niet, de valuta komt overeen, de operatie is niet geannuleerd en de status is nog niet "bijgeschreven". In het verzoek worden het bedrag en de externe betalingsidentificatie doorgegeven. Als de API van het paneel een idempotentiesleutel ondersteunt, gebruik dan dezelfde interne operatie-ID.

Algemene vorm van het verzoek: 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"}'

Vraag na het antwoord van het paneel opnieuw het saldo op en sla het resultaat op in het logboek. Als het geld bij de betaaldienst is afgeschreven, maar de API van het paneel een fout heeft teruggegeven, maak dan geen nieuwe betaling aan. De operatie blijft in de status "vereist controle" tot een nieuwe poging tot bijschrijving of handmatige afstemming. Het nadeel van zo'n voorzichtige aanpak is dat het saldo tijdelijk niet automatisch kan worden aangevuld.

Voeg meldingen, een schakelaar en een startcontrole toe

Meldingen zijn nodig voor afwijkingen: het saldo is onder het kritieke niveau gezakt, de betaling is geweigerd, de webhook is niet ontvangen, de limiet is overschreden, de API is onbeschikbaar of de operatie vereist handmatige controle. In het bericht volstaat het om de interne ID, de status en de oorzaak te vermelden. Neem er geen API-sleutels, webhook-handtekeningen en betaalgegevens in op.

Laat een afzonderlijke schakelaar voor automatische balansaanvulling staan zonder de integratie te verwijderen. Deze is nodig bij een wisseling van provider, technisch onderhoud, vermoeden van een fout of een plotselinge verandering van de kosten. Het nadeel van een schakelaar is duidelijk: als deze na onderhoud niet opnieuw wordt ingeschakeld, kan het saldo tijdens actieve bestellingen opraken.

Checklist vóór het inschakelen van automatische balansaanvulling

• De balanscontrole maakt geen betaling aan zolang er een onvoltooide operatie is.
• Voor elke betaling wordt een unieke interne ID en idempotentiesleutel aangemaakt.
• Er zijn limieten ingesteld voor één operatie en de gekozen periode.
• Webhooks worden gecontroleerd op handtekening, bedrag, valuta en identificatie.
• Bij het ontbreken van een webhook wordt een herhaalde statusafstemming via de API gestart.
• Een time-out leidt niet tot het aanmaken van een tweede betaling voordat de eerste is gecontroleerd.
• De bijschrijving in het paneel wordt één keer uitgevoerd en vastgelegd in het logboek.
• De testmodus is gecontroleerd op succes, weigering, dubbele webhook en onbeschikbaarheid van de API.