Automatisch opwaarderen van sub-accounts (Aangepaste betalingsprovider) #

Als u de creditbetalingen voor sub-accounts liever via uw eigen provider afhandelt in plaats van via Stripe (bankoverschrijvingen, lokale betalingsgateways, aangepaste facturatiesystemen), biedt het platform een webhook + API-paar zodat u het volledige proces van afschrijven en toekennen zelf kunt uitvoeren. Het niet-technische overzicht vindt u op de pagina Agency Accounts; deze pagina behandelt de exacte webhook-payload en de API-aanroep die u daarna doet om credits toe te kennen.

De webhook is slechts een van de manieren waarop automatische opwaarderingen worden betaald. Als je Stripe of PayPal in SaaS-modus hebt gekoppeld, brengt het platform de opgeslagen kaart of het PayPal-account van de klant zelf in rekening en worden de credits toegekend, dus je hoeft op deze pagina niets te bouwen. Lees alleen verder als je de betaling zelf wilt afhandelen.

Het proces in vogelvlucht #

1. Het creditsaldo van een sub-account daalt onder de drempelwaarde voor automatisch opwaarderen.
2. Het platform roept uw webhook-URL aan met de details van het sub-account en het aantal benodigde credits.
3. Uw server brengt de klant kosten in rekening via de provider die u gebruikt.
4. Uw server roept de API voor het toekennen van credits aan om credits toe te voegen aan dat sub-account.
5. Uw server reageert met 200 om de webhook te bevestigen.

1. Webhook: agency_sub_account_auto_recharge #

Configureer de webhook-URL door in de hoofdnavigatiebalk op SaaS Mode te klikken, Use a Custom Payment Provider Instead te kiezen (of, zodra geconfigureerd, de kaart Custom Payment Provider te openen) en het veld Auto-Recharge Webhook in te vullen.

Wanneer deze wordt geactiveerd #

Wanneer het creditsaldo van een sub-account onder de geconfigureerde drempelwaarde voor automatisch opwaarderen daalt.

Payload #

{
  "event": "agency_sub_account_auto_recharge",
  "sub_account_id": "<sub-account-id>",
  "sub_account_email": "customer@example.com",
  "sub_account_name": "John Doe",
  "agency_id": "<agency-id>",
  "credits_requested": 500,
  "current_balance": 42,
  "threshold": 100,
  "price_per_credit_cents": 10,
  "price_per_credit_currency": "usd",
  "total_amount_cents": 5000,
  "timestamp": "2026-04-13T12:00:00.000Z",
  "idempotency_key": "auto_recharge_abc123_1681387200000"
}

Belangrijke opmerkingen #

• Afkoelperiode van 5 minuten — Na een opwaardeerpoging voor een sub-account stuurt het platform gedurende ten minste 5 minuten geen nieuwe webhook voor dat sub-account, zelfs niet als het saldo verder daalt. Dit voorkomt dubbele afschrijvingen tijdens de verwerking.
• Gebruik de idempotentie-sleutel — Controleer altijd idempotency_key voordat u credits toekent. Als uw server crashte na het toekennen van credits maar vóór het reageren, kan het platform de webhook opnieuw verzenden bij de volgende daling van het saldo.
• Fouten zijn veilig en zelfherstellend — Als uw webhook-URL onbereikbaar is of een fout retourneert, worden er geen credits toegekend. Het platform blijft de webhook opnieuw verzenden (één keer per afkoelperiode van 5 minuten) zolang het sub-account onder de drempelwaarde blijft — het vereist niet dat het saldo eerst weer boven de drempelwaarde stijgt en opnieuw daalt. Een enkele gemiste afschrijving kan er niet langer voor zorgen dat een sub-account permanent niet wordt opgewaardeerd.
• Stel uw opwaardeerbedrag in op of boven de drempelwaarde — Uw geconfigureerde opwaardeerbedrag moet groter zijn dan of gelijk zijn aan de drempelwaarde voor automatisch opwaarderen, zodat één opwaardering het saldo altijd weer boven de drempelwaarde brengt. (Als u ooit een sub-account moet herstellen dat ver onder de drempelwaarde is gezakt, vult het platform het tekort automatisch volledig aan — zie credits_requested hierboven.)

2. API voor het toekennen van credits #

Nadat uw server de betaling heeft verwerkt, roept u dit eindpunt aan om de credits aan het sub-account toe te voegen.

Aanvraag #

POST https://api.dmchamp.com/v1/subaccounts/credits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "email": "customer@example.com",
  "amount": 500,
  "description": "Auto-recharge via webhook"
}

Authenticatie: Stuur uw API-sleutel in een request header — ofwel X-API-Key: YOUR_API_KEY of Authorization: Bearer YOUR_API_KEY. Headers zijn de aanbevolen methode, omdat een sleutel in de URL terechtkomt in de browsergeschiedenis, proxylogboeken en servertoegangslogboeken. De ?apiKey=YOUR_API_KEY queryparameter en een apiKey veld in de JSON-body werken ook nog steeds, zodat oudere integraties ongewijzigd blijven werken.

Reactie #

{
  "success": true,
  "sub_account_id": "abc123xyz",
  "credits_added": 500,
  "new_balance": 542
}

Wat gebeurt er met toegekende tegoeden bij de maandelijkse reset #

Dit hangt af van hoe het subaccount is ingesteld:

• Doorverkoop (het subaccount betaalt u voor tegoeden): tegoeden die u hier toekent, worden geregistreerd als gekochte tegoeden en worden elke maand meegenomen. Wat het subaccount niet heeft uitgegeven, blijft op het saldo staan.
• Toewijzing (u geeft het subaccount een maandelijkse toelage): het saldo wordt op de resetdatum aangevuld tot de maandelijkse toelage, dus alles wat niet is uitgegeven wordt niet meegenomen. Dit is opzettelijk — de toelage wordt elke maand opnieuw verstrekt.

Als u wilt dat het resterende saldo van een subaccount wordt opgeteld bij de nieuwe maandelijkse toelage in plaats van deze te vervangen, schakel dan tegoed-overdracht in:

PUT https://api.dmchamp.com/v1/subaccounts/{subAccountUid}/limits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "usageLimits": { "roll_over_to_next_month": true }
}

Als het subaccount — of het abonnement waarop het zich bevindt — ook een limiet voor overdracht of een vervaldatum heeft, is de reset het moment waarop deze van toepassing zijn: het overgedragen tegoed wordt ingekort tot de maanden die je toestaat, en tegoed dat langer dan de vervaltermijn ongebruikt is gebleven, komt te vervallen voordat het nieuwe tegoed wordt toegevoegd. Credits die via dit eindpunt zijn verleend, automatische opwaarderingen en de eigen opwaarderingen van de klant zijn eenmalige credits en worden nooit ingekort. Zie Limieten voor overdracht instellen.

End-to-end voorbeeld #

Een typische handler ziet er als volgt uit:

on POST /your-recharge-webhook:
  payload = request.body

  if seen(payload.idempotency_key):
    return 200  // already processed, ack and exit

  charge_result = your_payment_provider.charge(
    email = payload.sub_account_email,
    amount_cents = payload.total_amount_cents,
    currency = payload.price_per_credit_currency,
  )

  if not charge_result.ok:
    return 500  // platform will retry on next balance drop

  api.post("/v1/subaccounts/credits", {
    email = payload.sub_account_email,
    amount = payload.credits_requested,
    description = "Auto-recharge via " + your_provider_name,
  })

  mark_seen(payload.idempotency_key)
  return 200