Automatisk genopfyldning af underkonto (Brugerdefineret betalingsudbyder) #

Hvis du foretrækker at håndtere kreditbetalinger for underkonti via din egen udbyder i stedet for Stripe (bankoverførsler, lokale betalingsgateways, brugerdefinerede faktureringssystemer), stiller platformen et webhook + API-par til rådighed, så du selv kan køre hele processen med opkrævning og tildeling. Den ikke-tekniske oversigt findes på siden Agency Accounts; denne side dækker det præcise webhook-payload og det API-kald, du foretager for at tildele kreditter bagefter.

Webhook’en er kun én af måderne, hvorpå automatiske top-ups betales. Hvis du har forbundet Stripe eller PayPal i SaaS-tilstand, debiterer platformen selv kundens gemte kort eller PayPal-konto og tildeler kreditterne, så der er intet på denne side, du behøver at bygge. Læs kun videre, hvis du selv ønsker at håndtere betalingen.

Flowet i korte træk #

1. En underkontos kreditsaldo falder til under deres tærskel for automatisk genopfyldning.
2. Platformen kalder din webhook-URL med oplysninger om underkontoen og hvor mange kreditter de har brug for.
3. Din server opkræver betaling fra kunden via den udbyder, du bruger.
4. Din server kalder Grant Credits API for at tilføje kreditter til den pågældende underkonto.
5. Din server svarer 200 for at bekræfte modtagelsen af webhooket.

1. Webhook: agency_sub_account_auto_recharge #

Konfigurer webhook-URL’en ved at klikke på SaaS Mode i hovedsidepanelet, vælge Use a Custom Payment Provider Instead (eller, når den er konfigureret, åbne kortet Custom Payment Provider), og udfylde feltet Auto-Recharge Webhook.

Hvornår den udløses #

Når en underkontos kreditsaldo falder til under deres konfigurerede tærskel for automatisk genopfyldning.

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"
}

Vigtige bemærkninger #

• 5-minutters nedkøling — Efter et genopfyldningsforsøg for en underkonto sender platformen ikke et nyt webhook for den underkonto i mindst 5 minutter, selvom deres saldo falder yderligere. Dette forhindrer dobbelte opkrævninger under behandling.
• Brug idempotens-nøglen — Tjek altid idempotency_key, før du tildeler kreditter. Hvis din server gik ned efter at have tildelt kreditter, men før den svarede, kan platformen sende webhooket igen ved næste kreditfald.
• Fejl er sikre og selvhelbredende — Hvis din webhook-URL ikke kan nås eller returnerer en fejl, tildeles der ingen kreditter. Platformen bliver ved med at sende webhooket igen (én gang pr. 5-minutters nedkøling), så længe underkontoen forbliver under tærsklen — det kræver ikke, at saldoen først skal stige over tærsklen og falde igen. En enkelt mistet opkrævning kan ikke længere efterlade en underkonto permanent uden genopfyldning.
• Sæt dit genopfyldningsbeløb til eller over tærsklen — Dit konfigurerede genopfyldningsbeløb skal være større end eller lig med tærsklen for automatisk genopfyldning, så én genopfyldning altid bringer saldoen over tærsklen. (Hvis du nogensinde har brug for at rette en underkonto, der er drevet langt under tærsklen, fylder platformen den automatisk op med hele underskuddet — se credits_requested ovenfor.)

2. Grant Credits API #

Når din server har behandlet betalingen, skal du kalde dette endpoint for at tilføje kreditterne til underkontoen.

Anmodning #

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"
}

Godkendelse: Send din API-nøgle i en anmodningsheader — enten X-API-Key: YOUR_API_KEY eller Authorization: Bearer YOUR_API_KEY. Headere er den anbefalede metode, da en nøgle i URL’en ender i browserhistorik, proxylogfiler og serveradgangslogfiler. ?apiKey=YOUR_API_KEY-forespørgselsparameteren og et apiKey-felt i JSON-brødteksten fungerer også stadig, så ældre integrationer fortsætter med at køre uændret.

Svar #

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

Hvad sker der med tildelte kreditter ved den månedlige nulstilling #

Dette afhænger af, hvordan underkontoen er konfigureret:

• Videresalg (underkontoen betaler dig for kreditter): kreditter, du tildeler her, registreres som købte kreditter og overføres hver måned. Det, som underkontoen ikke har brugt, bliver stående på saldoen.
• Tildeling (du giver underkontoen en månedlig kvote): saldoen genopfyldes til den månedlige kvote på nulstillingsdatoen, så alt ubrugt beløb overføres ikke. Dette er tilsigtet – kvoten tildeles på ny hver måned.

Hvis du ønsker, at en underkontos resterende saldo skal lægges oven i dens nye månedlige kvote i stedet for at erstatte den, skal du aktivere kreditoverførsel:

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 }
}

Hvis underkontoen – eller den plan, den er tilknyttet – også har en grænse for overførsel eller en udløbsdato, er nulstillingen det tidspunkt, hvor disse træder i kraft: den overførte kvote beskæres til de måneder, du tillader, og kvote, der ikke er brugt i længere tid end udløbsvinduet, slettes, før den nye kvote tilføjes. Kreditter tildelt via dette endpoint, automatisk genopladning og kundens egne top-ups er engangskreditter og bliver aldrig beskåret. Se Begrænsning af hvad der overføres.

End-to-end eksempel #

En typisk håndtering ser således ud:

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