Automatisk påfyllning av underkonto (anpassad betalningsleverantör) #

Om du föredrar att hantera kreditbetalningar för underkonton via din egen leverantör istället för Stripe (banköverföringar, lokala betalväxlar, anpassade faktureringssystem), tillhandahåller plattformen ett par bestående av webhook + API så att du själv kan köra hela processen för debitering och tilldelning. Den icke-tekniska översikten finns på sidan Byråkonton; den här sidan täcker den exakta webhook-nyttolasten och det API-anrop du gör för att tilldela krediter efteråt.

Webbhooken är bara ett av sätten som automatiska påfyllningar betalas för. Om du har anslutit Stripe eller PayPal i SaaS-läge debiterar plattformen kundens sparade kort eller PayPal-konto direkt och tilldelar krediter, så det finns inget på den här sidan som du behöver bygga. Läs vidare endast om du vill hantera betalningen själv.

Flödet i korthet #

1. Ett underkontos kreditsaldo sjunker under deras tröskelvärde för automatisk påfyllning.
2. Plattformen anropar din webhook-URL med underkontots uppgifter och hur många krediter de behöver.
3. Din server debiterar kunden via den leverantör du använder.
4. Din server anropar API:et för att tilldela krediter för att lägga till krediter på det underkontot.
5. Din server svarar 200 för att bekräfta webhooken.

1. Webhook: agency_sub_account_auto_recharge #

Konfigurera webhook-URL:en genom att klicka på SaaS Mode i huvudsidofältet, välja Use a Custom Payment Provider Instead (eller, när den väl är konfigurerad, öppna kortet Custom Payment Provider), och fylla i fältet Auto-Recharge Webhook.

När den utlöses #

När ett underkontos kreditsaldo sjunker under deras konfigurerade tröskelvärde för automatisk påfyllning.

Nyttolast #

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

Viktiga anteckningar #

• 5 minuters nedkylning — Efter ett påfyllningsförsök för ett underkonto kommer plattformen inte att skicka en ny webhook för det underkontot på minst 5 minuter, även om deras saldo sjunker ytterligare. Detta förhindrar dubbla debiteringar under bearbetning.
• Använd idempotensnyckeln — Kontrollera alltid idempotency_key innan du tilldelar krediter. Om din server kraschade efter att ha tilldelat krediter men innan den svarade, kan plattformen skicka om webhooken vid nästa kreditfall.
• Fel är säkra och självläkande — Om din webhook-URL inte kan nås eller returnerar ett fel, tilldelas inga krediter. Plattformen fortsätter att skicka webhooken (en gång per 5-minuters nedkylning) så länge underkontot ligger under tröskelvärdet — det kräver inte att saldot först stiger över tröskelvärdet och sjunker igen. En missad debitering kan inte längre lämna ett underkonto permanent utan påfyllning.
• Ställ in ditt påfyllningsbelopp vid eller över tröskelvärdet — Ditt konfigurerade påfyllningsbelopp måste vara större än eller lika med tröskelvärdet för automatisk påfyllning, så att en påfyllning alltid återställer saldot över tröskelvärdet. (Om du någonsin behöver fixa ett underkonto som hamnat långt under tröskelvärdet, fyller plattformen automatiskt på hela underskottet — se credits_requested ovan.)

2. API för att tilldela krediter #

När din server har behandlat betalningen, anropa denna slutpunkt för att lägga till krediterna på underkontot.

Begäran #

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

Autentisering: Skicka din API-nyckel i en begärandehuvud — antingen X-API-Key: YOUR_API_KEY eller Authorization: Bearer YOUR_API_KEY. Huvuden är det rekommenderade sättet, eftersom en nyckel i URL:en hamnar i webbläsarhistorik, proxyloggar och serveråtkomstloggar. Frågeparametern ?apiKey=YOUR_API_KEY och ett apiKey-fält i JSON-kroppen fungerar fortfarande, så äldre integrationer fortsätter att fungera oförändrade.

Svar #

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

Vad händer med beviljade krediter vid den månatliga återställningen #

Detta beror på hur underkontot är konfigurerat:

• Återförsäljning (underkontot betalar dig för krediter): krediter som du beviljar här registreras som köpta krediter och överförs varje månad. Det som underkontot inte har förbrukat stannar kvar på saldot.
• Tilldelning (du ger underkontot en månatlig kvot): saldot fylls på till den månatliga kvoten på återställningsdatumet, så allt som inte förbrukats överförs inte. Detta är avsiktligt – kvoten beviljas på nytt varje månad.

Om du vill att ett underkontos kvarvarande saldo ska läggas till utöver dess nya månatliga kvot istället för att ersätta den, aktivera kreditöverföring:

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

Om underkontot – eller abonnemanget det tillhör – också har en gräns för överföring eller ett utgångsdatum, sker återställningen i det ögonblick dessa tillämpas: den överförda kvoten trimmas till det antal månader du tillåter, och kvot som lämnats oanvänd längre än utgångsperioden tas bort innan den nya kvoten läggs till. Krediter som beviljas via denna slutpunkt, automatiska påfyllningar och kundens egna påfyllningar är engångskrediter och trimmas aldrig. Se Begränsa vad som överförs.

Exempel från början till slut #

En typisk hanterare ser ut så här:

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