Israeli Payment Orchestrator

Step 1: Assess Payment Requirements

Ask the user about their payment needs:

Step 2: Compare Gateways

Use scripts/compare_gateways.py to generate a comparison matrix, or reference the table below:

Fee notes: Rates are indicative. Actual rates depend on business volume, industry, and negotiation.

Step 3: Design the Orchestration Layer

Build a unified payment abstraction:

# Unified payment interface pattern
class PaymentRequest:
    amount: float            # סכום - in agorot (NIS cents)
    currency: str            # מטבע - "ILS" default
    installments: int        # תשלומים - 1 = regular, 2-36 = installments
    installment_type: str    # סוג תשלומים - "regular", "credit", "club"
    card_token: str          # טוקן כרטיס - for recurring
    description: str         # תיאור עסקה
    customer_id: str         # מזהה לקוח
    idempotency_key: str     # מפתח אידמפוטנטי - prevent duplicates

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

Step 4: Implement Gateway Routing

Define routing rules for selecting the optimal gateway:

Routing logic:

def select_gateway(request: PaymentRequest, gateways: list) -> str:
    # 1. Filter by feature support (tashlumim type, Bit, etc.)
    eligible = [g for g in gateways if g.supports(request)]
    # 2. Remove unhealthy gateways
    healthy = [g for g in eligible if g.is_healthy()]
    # 3. Sort by cost for this transaction type
    ranked = sorted(healthy, key=lambda g: g.fee_for(request))
    # 4. Return best match (or raise if none available)
    return ranked[0] if ranked else raise NoGatewayAvailable()

Step 5: Handle Installments (Tashlumim)

Israeli installment types have specific Shva network rules:

Implementation notes:

• Maximum installments: typically 36, some gateways limit to 12 or 24
• Minimum per-installment: Shva may enforce minimum amounts per installment
• Installment approval: some installment counts require issuer pre-approval

Step 6: Implement Fallback and Retry Logic

Design resilient payment processing:

# Fallback strategy
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
            # Declined by bank -- do NOT retry with another gateway
            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)

Important: Never retry a bank decline (customer insufficient funds, stolen card, etc.) with a different gateway. Only retry on gateway technical errors.

Step 7: Ensure Regulatory Compliance

Comply with Bank of Israel and Shva regulations:

Example 1: Multi-Gateway Setup

User says: "I need to accept payments with installments, with fallback if one gateway goes down" Actions:

1. Assess: Need installments (regular + credit) and high availability
2. Compare: Cardcom (primary, full installment support) + Tranzila (fallback)
3. Design: Unified PaymentRequest with installment_type field
4. Implement: Route installment payments to Cardcom, failover to Tranzila
5. Run python scripts/compare_gateways.py --features installments,recurring Result: Orchestration layer with primary/fallback routing and installment handling

Example 2: Gateway Migration

User says: "We use Tranzila but want to add PayMe for Bit payments" Actions:

1. Assess: Current Tranzila setup + need Bit support
2. Design: Add PayMe as secondary gateway for Bit-eligible transactions
3. Route: Bit payments to PayMe, card payments to Tranzila
4. Implement: Unified response mapping between both gateway formats Result: Dual-gateway setup with feature-based routing

Example 3: Cost Optimization

User says: "Which gateway is cheapest for our 500 daily transactions averaging 200 NIS?" Actions:

1. Calculate: Monthly volume = 500 * 30 * 200 = 3,000,000 NIS
2. Compare: Run python scripts/compare_gateways.py --volume 500 --avg-amount 200
3. Factor: Installment mix, chargeback rates, settlement timing
4. Recommend: Based on total cost of ownership including integration effort Result: Cost comparison with recommendation based on business profile

Example 4: Installment Configuration

User says: "Customer wants to pay 5,000 NIS in 10 interest-free installments" Actions:

1. Identify: Regular installments (tashlumim regilim), 10 payments of 500 NIS
2. Check: Gateway support for 10 installments (all major gateways support this)
3. Note: Merchant absorbs interest cost for "interest-free" installments
4. Calculate: Merchant cost = typically 1-3% of transaction for interest subsidy
5. Implement: Set installments=10, installment_type="regular" in PaymentRequest Result: Installment payment configured with cost breakdown for merchant

Scripts

• scripts/compare_gateways.py -- Generates comparison matrix of Israeli payment gateways based on features, fees, and volume. Run: python scripts/compare_gateways.py --help

References

• references/gateway-matrix.md -- Detailed feature comparison of Israeli payment gateways: API formats, installment support, recurring billing, hosted pages, settlement timelines, and fee structures. Consult when evaluating or switching gateways.

Error: "Installment type not supported"

Cause: Requested installment type (credit/club) not available on selected gateway Solution: Check gateway capabilities in Step 2 table. Club installments only available on Cardcom and Pelecard. Route to appropriate gateway.

Error: "Shva clearing rejected"

Cause: Transaction violates Shva network rules (invalid installment count, amount below minimum) Solution: Verify installment count is within allowed range. Check minimum per-installment amount. Ensure transaction currency is ILS for domestic cards.

Error: "Gateway timeout on fallback"

Cause: All configured gateways are experiencing issues Solution: Implement circuit breaker pattern with health checks. Consider adding a third gateway. Monitor gateway status endpoints and alert on degradation.

Error: "Duplicate transaction detected"

Cause: Retry logic sent same payment to multiple gateways Solution: Always use idempotency keys. Check transaction status before retrying. Never retry bank declines -- only retry gateway technical errors.