טעינה אוטומטית של חשבון משנה (ספק תשלומים מותאם אישית) #

אם אתה מעדיף לנהל את תשלומי האשראי של חשבונות המשנה דרך ספק משלך במקום Stripe (העברות בנקאיות, שערי תשלום מקומיים, מערכות חיוב מותאמות אישית), הפלטפורמה חושפת זוג של webhook + API כך שתוכל להריץ את כל תהליך החיוב והענקת האשראי בעצמך. הסקירה הלא-טכנית נמצאת בדף חשבונות סוכנות; דף זה מכסה את מבנה ה-webhook המדויק ואת קריאת ה-API שעליך לבצע כדי להעניק את האשראי לאחר מכן.

ה-webhook הוא רק אחת הדרכים שבהן משולמים טעינות אוטומטיות. אם חיברת את Stripe או PayPal במצב SaaS, הפלטפורמה מחייבת בעצמה את הכרטיס השמור או את חשבון ה-PayPal של הלקוח ומעניקה את הקרדיטים, כך שאין לך מה לבנות בדף זה. המשך לקרוא רק אם ברצונך לטפל בתשלום בעצמך.

התהליך במבט חטוף #

1. יתרת האשראי של חשבון משנה יורדת מתחת לסף הטעינה האוטומטית שלו.
2. הפלטפורמה קוראת ל-webhook URL שלך עם פרטי חשבון המשנה וכמות האשראי שהם צריכים.
3. השרת שלך מחייב את הלקוח דרך הספק שבו אתה משתמש.
4. השרת שלך קורא ל-API להענקת אשראי כדי להוסיף אשראי לחשבון המשנה הזה.
5. השרת שלך מגיב ב-200 כדי לאשר את ה-webhook.

1. Webhook: agency_sub_account_auto_recharge #

הגדר את כתובת ה-URL של ה-webhook על ידי לחיצה על SaaS Mode בסרגל הצד הראשי, בחירה ב-Use a Custom Payment Provider Instead (או, לאחר ההגדרה, פתיחת הכרטיסייה Custom Payment Provider), ומילוי השדה Auto-Recharge Webhook.

מתי זה מופעל #

כאשר יתרת האשראי של חשבון משנה יורדת מתחת לסף הטעינה האוטומטית שהוגדר עבורו.

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

הערות חשובות #

• זמן המתנה של 5 דקות — לאחר ניסיון טעינה עבור חשבון משנה, הפלטפורמה לא תשלח webhook נוסף עבור אותו חשבון במשך 5 דקות לפחות, גם אם היתרה שלו תרד עוד יותר. זה מונע חיובים כפולים במהלך העיבוד.
• השתמש במפתח האידמפוטנטיות — בדוק תמיד את idempotency_key לפני הענקת אשראי. אם השרת שלך קרס לאחר הענקת האשראי אך לפני מתן תגובה, הפלטפורמה עשויה לשלוח שוב את ה-webhook בירידת האשראי הבאה.
• כשלים הם בטוחים ומתקנים את עצמם — אם כתובת ה-webhook שלך אינה נגישה או מחזירה שגיאה, לא יוענק אשראי. הפלטפורמה תמשיך לשלוח מחדש את ה-webhook (פעם אחת בכל זמן המתנה של 5 דקות) כל עוד חשבון המשנה נשאר מתחת לסף — היא לא דורשת שהיתרה תעלה חזרה מעל לסף ותרד שוב. חיוב אחד שפוספס לא יכול להשאיר חשבון משנה ללא טעינה לצמיתות.
• הגדר את סכום הטעינה שלך בגובה הסף או מעליו — סכום הטעינה שהגדרת חייב להיות גדול או שווה לסף הטעינה האוטומטית, כך שטעינה אחת תמיד תחזיר את היתרה מעל לסף. (אם אי פעם תצטרך לתקן חשבון משנה שירד הרבה מתחת לסף, הפלטפורמה תשלים אותו אוטומטית במלוא הגירעון — ראה credits_requested לעיל.)

2. API להענקת אשראי #

לאחר שהשרת שלך עיבד את התשלום, קרא לנקודת קצה (endpoint) זו כדי להוסיף את האשראי לחשבון המשנה.

בקשה #

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

אימות: שלח את מפתח ה-API שלך בכותרת בקשה — או X-API-Key: YOUR_API_KEY או Authorization: Bearer YOUR_API_KEY. כותרות הן הדרך המומלצת, מכיוון שמפתח בכתובת ה-URL מופיע בהיסטוריית הדפדפן, ביומני ה-proxy וביומני הגישה לשרת. הפרמטר ?apiKey=YOUR_API_KEY והשדה apiKey בגוף ה-JSON עדיין עובדים, כך שאינטגרציות ישנות ימשיכו לפעול ללא שינוי.

תגובה #

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

מה קורה לזיכויים שהוענקו בעת האיפוס החודשי #

זה תלוי באופן שבו מוגדר חשבון המשנה:

• מכירה חוזרת (חשבון המשנה משלם לך עבור זיכויים): זיכויים שאתה מעניק כאן נרשמים כזיכויים שנרכשו ועוברים בכל חודש. כל מה שחשבון המשנה לא ניצל נשאר ביתרת החשבון.
• הקצאה (אתה נותן לחשבון המשנה קצבה חודשית): היתרה מתמלאת מחדש לקצבה החודשית בתאריך האיפוס, כך שכל סכום שלא נוצל אינו עובר לחודש הבא. זה מכוון – הקצבה מוענקת מחדש בכל חודש.

אם ברצונך שיתרה שנותרה בחשבון משנה תתווסף על גבי הקצבה החודשית החדשה שלו במקום להחליף אותה, הפעל את העברת הזיכויים (credit roll-over):

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

אם לחשבון המשנה — או לתוכנית שבה הוא נמצא — יש גם הגבלת גלגול (roll-over cap) או תאריך תפוגה מוגדר, האיפוס מתרחש ברגע שהגדרות אלו חלות: הקצבה שגולגלה מצומצמת לחודשים שאתה מאפשר, והקצבה שלא נוצלה מעבר לחלון התפוגה נמחקת, לפני שהקצבה החדשה מתווספת. קרדיטים שניתנו דרך נקודת קצה זו, טעינות אוטומטיות וטעינות עצמיות של הלקוח הם קרדיטים חד-פעמיים ולעולם אינם מצומצמים. ראה הגבלת מה שמתגלגל.

דוגמה מקצה לקצה #

מטפל (handler) טיפוסי נראה כך:

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