DM Champ Docs

Automatyczne doładowanie subkonta (niestandardowy dostawca płatności)

Jeśli wolisz obsługiwać płatności za kredyty subkont za pośrednictwem własnego dostawcy zamiast Stripe (przelewy bankowe, lokalne bramki płatności, niestandardowe systemy rozliczeniowe), platforma udostępnia parę webhook + API, dzięki czemu możesz samodzielnie przeprowadzić pełny proces obciążenia i przyznania środków. Nietechniczny przegląd znajduje się na stronie Konta agencyjne; ta strona zawiera szczegółowe informacje o ładunku webhooka oraz wywołaniu API, które należy wykonać, aby następnie przyznać kredyty.

Webhook to tylko jeden ze sposobów opłacania automatycznych doładowań. Jeśli połączyłeś Stripe lub PayPal w trybie SaaS, platforma sama obciąża zapisaną kartę lub konto PayPal klienta i przyznaje kredyty, więc nie musisz niczego budować na tej stronie. Czytaj dalej tylko wtedy, gdy chcesz samodzielnie obsługiwać płatności.

Przegląd procesu

  1. Saldo kredytów subkonta spada poniżej progu automatycznego doładowania.
  2. Platforma wywołuje Twój adres URL webhooka z danymi subkonta i informacją, ile kredytów potrzebuje.
  3. Twój serwer obciąża klienta za pośrednictwem wybranego dostawcy.
  4. Twój serwer wywołuje API przyznawania kredytów, aby dodać kredyty do tego subkonta.
  5. Twój serwer odpowiada 200, aby potwierdzić otrzymanie webhooka.

1. Webhook: agency_sub_account_auto_recharge

Skonfiguruj adres URL webhooka, klikając Tryb SaaS na głównym pasku bocznym, wybierając Użyj zamiast tego niestandardowego dostawcy płatności (lub, po skonfigurowaniu, otwierając kartę Niestandardowy dostawca płatności) i wypełniając pole Webhook automatycznego doładowania.

Kiedy jest wyzwalane

Gdy saldo kredytów subkonta spadnie poniżej skonfigurowanego progu automatycznego doładowania.

Ładunek (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"
}
Pole Opis
event Zawsze agency_sub_account_auto_recharge dla tego webhooka.
sub_account_id Unikalny identyfikator subkonta, które potrzebuje kredytów.
sub_account_email Adres e-mail subkonta.
sub_account_name Nazwa wyświetlana subkonta.
agency_id Unikalny identyfikator Twojego konta agencyjnego.
credits_requested Liczba kredytów do przyznania. Jest to Twoja skonfigurowana kwota doładowania, ale jeśli saldo spadło poniżej progu bardziej, niż pokryłaby ta kwota, zostanie ona automatycznie zwiększona do wartości niezbędnej, aby przywrócić saldo powyżej progu za jednym razem. Zawsze obciążaj (i przyznawaj) wartość credits_requested z ładunku — nie koduj na sztywno kwoty doładowania.
current_balance Saldo kredytów subkonta w momencie wysłania webhooka.
threshold Próg salda, który wywołał doładowanie.
price_per_credit_cents Twoja skonfigurowana cena za kredyt w centach.
price_per_credit_currency Waluta ceny (np. usd).
total_amount_cents Całkowita kwota do obciążenia w centach (credits_requested × price_per_credit_cents).
timestamp Kiedy wysłano webhook (format ISO 8601).
idempotency_key Unikalny klucz dla tego konkretnego żądania doładowania. Użyj go, aby zapobiec dwukrotnemu przyznaniu kredytów, jeśli Twój serwer otrzyma ten sam webhook więcej niż raz.

Ważne uwagi

  • 5-minutowy czas oczekiwania — Po próbie doładowania subkonta platforma nie wyśle kolejnego webhooka dla tego subkonta przez co najmniej 5 minut, nawet jeśli jego saldo spadnie jeszcze bardziej. Zapobiega to podwójnym obciążeniom podczas przetwarzania.
  • Użyj klucza idempotencji — Zawsze sprawdzaj idempotency_key przed przyznaniem kredytów. Jeśli Twój serwer uległ awarii po przyznaniu kredytów, ale przed wysłaniem odpowiedzi, platforma może ponownie wysłać webhook przy następnym spadku kredytów.
  • Błędy są bezpieczne i samonaprawialne — Jeśli Twój adres URL webhooka jest nieosiągalny lub zwraca błąd, kredyty nie zostaną przyznane. Platforma ponawia wysyłanie webhooka (raz na 5-minutowy okres oczekiwania), dopóki subkonto pozostaje poniżej progu — nie wymaga to, aby saldo najpierw wzrosło powyżej progu, a potem ponownie spadło. Pojedyncze pominięte obciążenie nie może już pozostawić subkonta trwale bez doładowania.
  • Ustaw kwotę doładowania na poziomie progu lub powyżej — Twoja skonfigurowana kwota doładowania musi być większa lub równa progowi automatycznego doładowania, aby jedno doładowanie zawsze przywracało saldo powyżej progu. (Jeśli kiedykolwiek będziesz musiał naprawić subkonto, które spadło znacznie poniżej progu, platforma automatycznie uzupełni je o pełny deficyt — patrz credits_requested powyżej).

2. API przyznawania kredytów

Po przetworzeniu płatności przez Twój serwer wywołaj ten punkt końcowy, aby dodać kredyty do subkonta.

Żądanie 

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"
}
Pole Wymagane Opis
email Tak Adres e-mail subkonta (musi pasować do istniejącego subkonta w ramach Twojej agencji).
amount Tak Liczba kredytów do przyznania.
description Nie Notatka opisująca powód dodania kredytów (widoczna w historii transakcji kredytowych).

Uwierzytelnianie: Wyślij swój klucz API w nagłówku żądania — albo X-API-Key: YOUR_API_KEY, albo Authorization: Bearer YOUR_API_KEY. Nagłówki są zalecaną metodą, ponieważ klucz w adresie URL trafia do historii przeglądarki, logów serwera proxy i logów dostępu serwera. Parametr zapytania ?apiKey=YOUR_API_KEY oraz pole apiKey w treści JSON również nadal działają, dzięki czemu starsze integracje będą działać bez zmian.

Odpowiedź 

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

Wskazówka: Zapisz idempotency_key z ładunku webhooka i sprawdź go przed wywołaniem tego punktu końcowego. Zapobiega to przypadkowemu przyznaniu kredytów dwukrotnie, jeśli Twój serwer otrzyma ten sam webhook więcej niż raz.

Co dzieje się z przyznanymi kredytami podczas comiesięcznego resetu

Zależy to od sposobu skonfigurowania subkonta:

  • Odsprzedaż (subkonto płaci Ci za kredyty): przyznane tutaj kredyty są rejestrowane jako zakupione i przechodzą na kolejny miesiąc. Wszystko, czego subkonto nie wydało, pozostaje na saldzie.
  • Przydział (dajesz subkontu miesięczny limit): saldo jest uzupełniane do wysokości miesięcznego limitu w dniu resetu, więc niewykorzystane środki nie przechodzą na kolejny miesiąc. Jest to zamierzone działanie — limit jest przyznawany od nowa każdego miesiąca.

Jeśli chcesz, aby pozostałe saldo subkonta było dodawane do nowego miesięcznego limitu zamiast go zastępować, włącz przenoszenie kredytów:

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

Jeśli subkonto — lub plan, z którego korzysta — ma również ustawiony limit przenoszenia środków lub datę wygaśnięcia, reset następuje w momencie ich zastosowania: przeniesiony limit jest przycinany do liczby miesięcy, na które pozwalasz, a limit niewykorzystany przez okres dłuższy niż okno wygaśnięcia jest usuwany przed dodaniem nowego limitu. Kredyty przyznane za pośrednictwem tego punktu końcowego, automatyczne doładowania oraz własne doładowania klienta są kredytami jednorazowymi i nigdy nie są przycinane. Zobacz Ograniczanie tego, co przechodzi na kolejny okres.

Przykład kompleksowy

Typowy program obsługi wygląda następująco:

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