תזמור תשלומים ישראלי

שלב 1: הערכת דרישות תשלום

שאלו את המשתמש על צרכי התשלום שלו:

שלב 2: השוואת שערי תשלום

השתמשו ב-scripts/compare_gateways.py ליצירת מטריצת השוואה, או עיינו בטבלה:

הערת עמלות: התעריפים אינדיקטיביים. עמלות בפועל תלויות בנפח, ענף ומשא ומתן.

שלב 3: עיצוב שכבת התזמור

בנו הפשטת תשלום אחידה:

# תבנית ממשק תשלום אחיד
class PaymentRequest:
    amount: float            # סכום - באגורות
    currency: str            # מטבע - "ILS" ברירת מחדל
    installments: int        # תשלומים - 1 = רגיל, 2-36 = תשלומים
    installment_type: str    # סוג תשלומים - "regular", "credit", "club"
    card_token: str          # טוקן כרטיס - לחיוב חוזר
    description: str         # תיאור עסקה
    customer_id: str         # מזהה לקוח
    idempotency_key: str     # מפתח אידמפוטנטי - למניעת כפילויות

class PaymentResult:
    success: bool
    gateway_used: str        # שער תשלום שנבחר
    transaction_id: str      # מזהה עסקה
    approval_number: str     # מספר אישור
    shva_reference: str      # מספר שב"א
    installment_details: dict

שלב 4: מימוש ניתוב שערים

הגדירו כללי ניתוב לבחירת השער האופטימלי:

שלב 5: טיפול בתשלומים

לסוגי תשלומים ישראליים כללים ספציפיים ברשת שב"א:

הערות מימוש:

• מקסימום תשלומים: בדרך כלל 36, חלק מהשערים מגבילים ל-12 או 24
• מינימום לתשלום: שב"א עשוי לאכוף סכומי מינימום לתשלום
• אישור תשלומים: חלק ממספרי התשלומים דורשים אישור מנפיק מראש

שלב 6: מימוש Fallback ולוגיקת ניסיון חוזר

עצבו עיבוד תשלומים עמיד:

# אסטרטגיית fallback
GATEWAY_PRIORITY = ["cardcom", "tranzila", "payme"]

async def process_with_fallback(request: PaymentRequest) -> PaymentResult:
    last_error = None
    for gateway_name in GATEWAY_PRIORITY:
        gateway = get_gateway(gateway_name)
        if not gateway.is_healthy():
            continue  # דלג על שער לא זמין
        try:
            result = await gateway.charge(request)
            if result.success:
                return result
            # סירוב בנקאי -- אל תנסו שער אחר
            if result.is_bank_decline():
                return result
        except GatewayTimeoutError:
            last_error = f"{gateway_name} timeout"
            continue  # נסה שער הבא
        except GatewayError as e:
            last_error = str(e)
            continue
    raise AllGatewaysFailedError(last_error)

חשוב: לעולם אל תנסו שוב סירוב בנקאי (אין כיסוי, כרטיס גנוב וכו') בשער אחר. נסו שוב רק בשגיאות טכניות של שער.

שלב 7: הבטחת עמידה ברגולציה

עמדו בדרישות בנק ישראל ושב"א:

דוגמה 1: הקמת ריבוי שערים

המשתמש אומר: "אני צריך לקבל תשלומים עם תשלומים, עם fallback אם שער אחד נופל" פעולות:

1. הערכה: צורך בתשלומים (רגילים + קרדיט) וזמינות גבוהה
2. השוואה: Cardcom (ראשי, תמיכה מלאה בתשלומים) + Tranzila (גיבוי)
3. עיצוב: PaymentRequest אחיד עם שדה installment_type
4. מימוש: ניתוב תשלומים ל-Cardcom, failover ל-Tranzila
5. הרצת python scripts/compare_gateways.py --features installments,recurring תוצאה: שכבת תזמור עם ניתוב ראשי/גיבוי וטיפול בתשלומים

דוגמה 2: מעבר בין שערים

המשתמש אומר: "אנחנו משתמשים ב-Tranzila אבל רוצים להוסיף PayMe לתשלומי ביט" פעולות:

1. הערכה: הגדרת Tranzila קיימת + צורך בתמיכת ביט
2. עיצוב: הוספת PayMe כשער משני לעסקאות ביט
3. ניתוב: תשלומי ביט ל-PayMe, תשלומי כרטיס ל-Tranzila
4. מימוש: מיפוי תגובות אחיד בין שני פורמטי השערים תוצאה: הגדרת שער כפול עם ניתוב מבוסס פיצ'רים

דוגמה 3: אופטימיזציית עלויות

המשתמש אומר: "איזה שער הכי זול ל-500 עסקאות יומיות ממוצע 200 ש"ח?" פעולות:

1. חישוב: נפח חודשי = 500 * 30 * 200 = 3,000,000 ש"ח
2. השוואה: הרצת python scripts/compare_gateways.py --volume 500 --avg-amount 200
3. שקלול: תמהיל תשלומים, שיעורי chargebacks, תזמון גמר חשבון
4. המלצה: על בסיס עלות כוללת כולל מאמץ אינטגרציה תוצאה: השוואת עלויות עם המלצה על בסיס פרופיל העסק

דוגמה 4: הגדרת תשלומים

המשתמש אומר: "לקוח רוצה לשלם 5,000 ש"ח ב-10 תשלומים ללא ריבית" פעולות:

1. זיהוי: תשלומים רגילים, 10 תשלומים של 500 ש"ח
2. בדיקה: תמיכת שער ב-10 תשלומים (כל השערים המרכזיים תומכים)
3. הערה: בית העסק סופג עלות ריבית בתשלומים "ללא ריבית"
4. חישוב: עלות לבית העסק = בדרך כלל 1-3% מהעסקה לסבסוד ריבית
5. מימוש: הגדרת installments=10, installment_type="regular" ב-PaymentRequest תוצאה: תשלום בתשלומים מוגדר עם פירוט עלויות לבית העסק

סקריפטים

• scripts/compare_gateways.py -- הפקת מטריצת השוואה של שערי תשלום ישראליים לפי פיצ'רים, עמלות ונפח. הרצה: python scripts/compare_gateways.py --help

חומרי עזר

• references/gateway-matrix.md -- השוואת פיצ'רים מפורטת של שערי תשלום ישראליים: פורמטי API, תמיכת תשלומים, חיוב חוזר, דפים מאוחסנים, לוחות זמני גמר חשבון ומבני עמלות. היעזרו בקובץ זה בעת הערכה או החלפת שערים.

שגיאה: "סוג תשלומים לא נתמך"

סיבה: סוג תשלומים מבוקש (קרדיט/מועדון) לא זמין בשער הנבחר פתרון: בדקו יכולות שער בטבלת שלב 2. תשלומי מועדון זמינים רק ב-Cardcom ו-Pelecard. נתבו לשער המתאים.

שגיאה: "סליקת שב"א נדחתה"

סיבה: עסקה מפרה כללי רשת שב"א (מספר תשלומים לא חוקי, סכום מתחת למינימום) פתרון: ודאו שמספר התשלומים בטווח המותר. בדקו סכום מינימום לתשלום. ודאו שמטבע העסקה הוא ILS לכרטיסים מקומיים.

שגיאה: "Gateway timeout ב-fallback"

סיבה: כל השערים המוגדרים חווים בעיות פתרון: מימשו תבנית circuit breaker עם בדיקות בריאות. שקלו הוספת שער שלישי. נטרו נקודות קצה סטטוס של שערים והתריעו על הידרדרות.

שגיאה: "זוהתה עסקה כפולה"

סיבה: לוגיקת ניסיון חוזר שלחה אותו תשלום למספר שערים פתרון: השתמשו תמיד במפתחות אידמפוטנטיים. בדקו סטטוס עסקה לפני ניסיון חוזר. לעולם אל תנסו שוב סירוב בנקאי -- נסו שוב רק בשגיאות טכניות של שער.