Israeli Payment Orchestrator

{
  "schemaVersion": "1.0",
  "skill": "israeli-payment-orchestrator",
  "generated_at": "2026-06-07T00:00:00Z",
  "claims": [
    {
      "claim_id": "shva-credittype-codes",
      "claim": "Shva CreditType (סוג אשראי) enum, a field distinct from transaction type (סוג עסקה): 1=regular/immediate, 2=Isracredit/30+, 3=immediate debit, 4=club credit, 5=Leumi special, 6=credit installments (קרדיט, interest to bank), 8=regular installments (תשלומים, merchant-financed), 9=club installments (מועדון). Interest-free installments use CreditType 8 (merchant subsidizes). Credit (קרדיט) is 6, NOT 2; club installments are 9, NOT 3.",
      "source_url": "https://github.com/astrails/active_merchant_tranzila",
      "raw_snippet": "cred_type: 1 Regular, 2 Isracredit/30+, 3 Immediate debit, 4 Club Credit, 5 Leumi special, 6 Credit (קרדיט), 8 Installments (תשלומים), 9 Club installments (מועדון).",
      "fetched_at": "2026-06-07T00:00:00Z",
      "appears_in": ["SKILL.md", "SKILL_HE.md", "references/gateway-matrix.md"]
    },
    {
      "claim_id": "installment-types",
      "claim": "Installment type semantics: regular installments (תשלומים) - merchant gets the full amount upfront, the bank collects from the customer monthly, no interest by default; credit installments (קרדיט) - the customer pays the bank in installments with interest, merchant gets full amount; club installments (מועדון) - issuer-specific program (Isracard, CAL, Max). Maximum installments typically 36 (some gateways cap at 12 or 24); Shva may enforce a minimum per-installment amount.",
      "source_url": "https://docs.tranzila.com/",
      "raw_snippet": "תשלומים רגילים: בית העסק מקבל את מלוא הסכום, הבנק גובה מהלקוח חודשית ללא ריבית; קרדיט: הלקוח משלם לבנק עם ריבית; מועדון: תוכנית מנפיק. עד 36 תשלומים (חלק מהשערים עד 12/24).",
      "fetched_at": "2026-06-07T00:00:00Z",
      "appears_in": ["SKILL.md", "SKILL_HE.md", "references/gateway-matrix.md"]
    },
    {
      "claim_id": "gateway-api-styles",
      "claim": "Gateway API styles: Cardcom REST JSON; Tranzila REST / form-POST (form-encoded key-value); PayMe bearer-token REST JSON; Meshulam/Grow multipart/form-data (NOT JSON), server-side only, Light API at secure.meshulam.co.il/api/light/server/1.0/; iCredit REST JSON; Pelecard REST JSON. Bit support by default: PayMe yes, Meshulam yes, others no. Fee ranges (0.5-1.0%) are indicative and negotiation-dependent.",
      "source_url": "https://grow-il.readme.io/reference/overview",
      "raw_snippet": "Grow (Meshulam) Light API requires multipart/form-data, not JSON, server-side only; Cardcom uses JSON; Tranzila uses form-encoded params; PayMe uses bearer-token JSON.",
      "fetched_at": "2026-06-07T00:00:00Z",
      "appears_in": ["SKILL.md", "SKILL_HE.md", "references/gateway-matrix.md", "scripts/compare_gateways.py"]
    },
    {
      "claim_id": "regulation",
      "claim": "Israeli payment-services regulation: the Regulation of Payment Services and Payment Initiation Law 5783-2023 makes the Israel Securities Authority (ISA) the primary regulator of non-bank payment service providers; the Bank of Israel supervises banks and credit-card companies and oversees Shva as a controlled payment system. Shva (שב\"א, Automatic Bank Services) still operates the credit-card clearing network. Transaction data retention 7 years; PCI DSS tokenization (never store full PANs); 3DS2 for card-not-present transactions.",
      "source_url": "https://www.boi.org.il/en/economic-roles/supervision-and-regulation/payment-systems-oversight/",
      "raw_snippet": "חוק הסדרת העיסוק בשירותי תשלום ויוזמה בתשלום, התשפ\"ג-2023: רשות ניירות ערך מפקחת על נותני שירותי תשלום שאינם בנק; בנק ישראל מפקח על הבנקים וחברות כרטיסי האשראי ומפקח על שב\"א.",
      "fetched_at": "2026-06-07T00:00:00Z",
      "appears_in": ["SKILL.md", "SKILL_HE.md"]
    },
    {
      "claim_id": "reference-urls-and-figures",
      "claim": "Reference URLs for the gateways and the BOI oversight page, plus illustrative figures (idempotency, agorot amounts, 60/40 volume split, 3,000,000 NIS example volume, 5,000 NIS / 500 NIS / 200 NIS example amounts, 1-3% interest-subsidy estimate, 1,000 transactions/day, T+2/T+3 settlement). These figures are illustrative or indicative.",
      "source_url": "https://www.boi.org.il/en/economic-roles/supervision-and-regulation/payment-systems-oversight/",
      "raw_snippet": "URLs: https://www.cardcom.co.il/ https://docs.tranzila.com/ https://www.payme.io/developers https://grow-il.readme.io/reference/overview https://icredit.rivhit.co.il/ https://www.boi.org.il/en/economic-roles/supervision-and-regulation/payment-systems-oversight/ https://www.boi.org.il/he/economic-roles/supervision-and-regulation/payment-systems-oversight/ . Gateway base URLs (gateway-matrix): https://secure.cardcom.solutions/api/ https://kb.cardcom.co.il/ https://secure5.tranzila.com/ https://ng.paymeservice.com/api/ https://secure.meshulam.co.il/api/light/server/1.0/ https://sandbox.meshulam.co.il/api/light/server/1.0/ https://icredit.rivhit.co.il/api/ https://gateway20.pelecard.biz/ https://www.pelecard.com/support/ . Indicative fee percentages: 0.5%, 0.6%, 0.7%, 0.8%, 0.9%, 1.0%. Illustrative amounts: 60/40 split, 3,000,000 NIS, 3,000,000 ש\"ח, 5,000 NIS, 5,000 ש\"ח, 500 NIS, 500 ש\"ח, 200 NIS, 200 ש\"ח, 1-3%, 1,000 transactions/day, T+2/T+3.",
      "fetched_at": "2026-06-07T00:00:00Z",
      "appears_in": ["SKILL.md", "SKILL_HE.md", "references/gateway-matrix.md", "scripts/compare_gateways.py"]
    }
  ]
}

{
  "author": "skills-il",
  "version": "1.1.1",
  "category": "tax-and-finance",
  "tags": {
    "he": [
      "תשלומים",
      "סליקה",
      "שב\"א",
      "כרטיסי-אשראי",
      "תשלומים-נדחים",
      "ישראל"
    ],
    "en": [
      "payments",
      "gateway",
      "shva",
      "credit-cards",
      "installments",
      "israel"
    ]
  },
  "display_name": {
    "he": "תזמור תשלומים ישראלי",
    "en": "Israeli Payment Orchestrator"
  },
  "display_description": {
    "he": "תזמור שערי תשלום ישראליים (Cardcom, Tranzila, PayMe, Meshulam, iCredit, Pelecard) עם ניתוב אחיד, fallback ותשלומים. כולל השוואת שערים, טיפול בתשלומים ועמידה בהנחיות בנק ישראל.",
    "en": "Orchestrate Israeli payment gateways (Cardcom, Tranzila, PayMe, Meshulam, iCredit, Pelecard) with unified routing, fallback, and installments (tashlumim). Use when user asks about multi-gateway payment integration, \"slikat kartisim\", \"tashlumim\", payment routing, Shva network, BOI payment-services regulation, gateway comparison, or building a payment abstraction layer for Israeli merchants. Provides unified API patterns, installment handling, Shva clearing rules, and regulatory compliance. Do NOT use for single gateway setup (use cardcom-payment-gateway or tranzila-payment-gateway instead)."
  },
  "supported_agents": [
    "claude-code",
    "cursor",
    "github-copilot",
    "windsurf",
    "opencode",
    "codex",
    "antigravity",
    "gemini-cli"
  ]
}

{
  "cycles": [
    {
      "version": "1.1.1",
      "date": "2026-06-07",
      "lessons": [
        "CRITICAL: the Shva CreditType (סוג אשראי) codes were wrong and transaction-breaking. Skill had credit (קרדיט)=2 and club (מועדון)=3; correct is credit=6 and club installments=9 (club credit=4). Regular installments (תשלומים)=8 was correct. Fixed Step 5 in SKILL.md + SKILL_HE.md and the gateway-matrix Shva codes table, and clarified that CreditType is a distinct field from transaction type (סוג עסקה).",
        "MAJOR: Meshulam/Grow API style was listed as REST JSON in three places (SKILL.md + SKILL_HE.md Step 2 tables, gateway-matrix, compare_gateways.py) while the Gotcha correctly said multipart/form-data; fixed all to multipart/form-data and corrected the Meshulam base path + docs URL (grow-il.readme.io).",
        "Fixed the dead BOI reference link (boi.org.il/en/banking/payment-systems 404) to the payment-systems-oversight path, and sharpened the regulator framing: non-bank PSPs are regulated by the ISA under the Regulation of Payment Services and Payment Initiation Law 5783-2023; the BOI supervises banks/credit-card cos and oversees Shva.",
        "Built evidence.json from scratch (legacy skill); stripped 3 em-dashes from SKILL_HE.md.",
        "Deferred MINOR: the 'club installments only on Cardcom/Pelecard' claim likely understates Tranzila (which supports cred_type 9); gateway capability tables are terminal-config-dependent, revisit if a capability refresh is done."
      ]
    }
  ]
}

#!/usr/bin/env python3
"""Compare Israeli payment gateways based on features, fees, and volume.

Generates a comparison matrix to help choose the right payment gateway(s)
for Israeli merchants. Supports filtering by features and volume-based
cost estimation.

Usage:
    python scripts/compare_gateways.py --features installments,recurring
    python scripts/compare_gateways.py --volume 500 --avg-amount 200
    python scripts/compare_gateways.py --all
    python scripts/compare_gateways.py --example
"""

import sys
import json
import argparse
from dataclasses import dataclass, asdict, field
from typing import List, Optional


@dataclass
class GatewayInfo:
    """Israeli payment gateway information."""
    name: str
    hebrew_name: str
    api_style: str
    installment_types: List[str]
    recurring: bool
    hosted_page: str
    bit_support: bool
    apple_pay: bool
    fee_range_pct: tuple  # (min, max) percentage
    settlement_days: int  # typical settlement time
    api_docs_url: str
    notes: str


# שערי תשלום ישראליים - Israeli payment gateways database
GATEWAYS = {
    "cardcom": GatewayInfo(
        name="Cardcom",
        hebrew_name="קארדקום",
        api_style="REST JSON",
        installment_types=["regular", "credit", "club"],
        recurring=True,
        hosted_page="iframe",
        bit_support=False,
        apple_pay=False,
        fee_range_pct=(0.6, 0.8),
        settlement_days=2,
        api_docs_url="https://kb.cardcom.co.il/",
        notes="Full installment support including club. Good documentation.",
    ),
    "tranzila": GatewayInfo(
        name="Tranzila",
        hebrew_name="טרנזילה",
        api_style="REST / Form POST",
        installment_types=["regular", "credit"],
        recurring=True,
        hosted_page="redirect",
        bit_support=False,
        apple_pay=False,
        fee_range_pct=(0.5, 0.7),
        settlement_days=2,
        api_docs_url="https://docs.tranzila.com/",
        notes="Veteran provider. Lower fees. Form POST legacy API still common.",
    ),
    "payme": GatewayInfo(
        name="PayMe",
        hebrew_name="פיימי",
        api_style="REST JSON",
        installment_types=["regular", "credit"],
        recurring=True,
        hosted_page="iframe",
        bit_support=True,
        apple_pay=True,
        fee_range_pct=(0.7, 1.0),
        settlement_days=2,
        api_docs_url="https://www.payme.io/developers",
        notes="Modern API. Bit and Apple Pay support. Higher fees.",
    ),
    "meshulam": GatewayInfo(
        name="Meshulam",
        hebrew_name="משולם",
        api_style="multipart/form-data",
        installment_types=["regular"],
        recurring=True,
        hosted_page="iframe + redirect",
        bit_support=True,
        apple_pay=False,
        fee_range_pct=(0.6, 0.9),
        settlement_days=3,
        api_docs_url="https://grow-il.readme.io/reference/overview",
        notes="Popular with SMBs. Bit support. Limited installment types.",
    ),
    "icredit": GatewayInfo(
        name="iCredit",
        hebrew_name="אייקרדיט",
        api_style="REST JSON",
        installment_types=["regular", "credit"],
        recurring=True,
        hosted_page="redirect",
        bit_support=False,
        apple_pay=False,
        fee_range_pct=(0.5, 0.8),
        settlement_days=2,
        api_docs_url="https://icredit.rivhit.co.il/",
        notes="Part of Rivhit (accounting software). Good for existing Rivhit users.",
    ),
    "pelecard": GatewayInfo(
        name="Pelecard",
        hebrew_name="פלאכארד",
        api_style="REST JSON",
        installment_types=["regular", "credit", "club"],
        recurring=True,
        hosted_page="iframe",
        bit_support=False,
        apple_pay=False,
        fee_range_pct=(0.5, 0.7),
        settlement_days=2,
        api_docs_url="https://www.pelecard.com/support/",
        notes="Full installment support. Competitive pricing for high volume.",
    ),
}


def filter_by_features(gateways: dict, features: List[str]) -> dict:
    """Filter gateways by required features.

    Args:
        gateways: Dictionary of gateway name to GatewayInfo.
        features: List of required features.

    Returns:
        Filtered dictionary of gateways that support all features.
    """
    result = {}
    for name, gw in gateways.items():
        matches = True
        for feature in features:
            feature = feature.strip().lower()
            if feature == "installments" and not gw.installment_types:
                matches = False
            elif feature == "credit" and "credit" not in gw.installment_types:
                matches = False
            elif feature == "club" and "club" not in gw.installment_types:
                matches = False
            elif feature == "recurring" and not gw.recurring:
                matches = False
            elif feature == "bit" and not gw.bit_support:
                matches = False
            elif feature == "apple_pay" and not gw.apple_pay:
                matches = False
        if matches:
            result[name] = gw
    return result


def estimate_monthly_cost(
    gateway: GatewayInfo,
    daily_volume: int,
    avg_amount: float,
) -> dict:
    """Estimate monthly processing cost for a gateway.

    Args:
        gateway: Gateway information.
        daily_volume: Average daily transaction count.
        avg_amount: Average transaction amount in NIS.

    Returns:
        Dictionary with cost estimates.
    """
    monthly_transactions = daily_volume * 30
    monthly_volume_nis = monthly_transactions * avg_amount
    min_fee = monthly_volume_nis * (gateway.fee_range_pct[0] / 100)
    max_fee = monthly_volume_nis * (gateway.fee_range_pct[1] / 100)
    avg_fee = (min_fee + max_fee) / 2

    return {
        "gateway": gateway.name,
        "monthly_transactions": monthly_transactions,
        "monthly_volume_nis": monthly_volume_nis,
        "fee_range_pct": f"{gateway.fee_range_pct[0]}-{gateway.fee_range_pct[1]}%",
        "monthly_fee_min_nis": round(min_fee, 0),
        "monthly_fee_max_nis": round(max_fee, 0),
        "monthly_fee_avg_nis": round(avg_fee, 0),
    }


def print_comparison_table(gateways: dict) -> None:
    """Print gateway comparison as formatted table."""
    print(f"\n{'Gateway':<12} {'API':<18} {'Installments':<25} {'Recurring':<10} "
          f"{'Hosted':<18} {'Bit':<5} {'Fee':<10}")
    print("-" * 100)
    for name, gw in gateways.items():
        inst = ", ".join(gw.installment_types) if gw.installment_types else "None"
        fee = f"{gw.fee_range_pct[0]}-{gw.fee_range_pct[1]}%"
        print(f"{gw.name:<12} {gw.api_style:<18} {inst:<25} "
              f"{'Yes' if gw.recurring else 'No':<10} "
              f"{gw.hosted_page:<18} {'Yes' if gw.bit_support else 'No':<5} {fee:<10}")


def print_cost_comparison(gateways: dict, daily_volume: int, avg_amount: float) -> None:
    """Print cost comparison for given volume."""
    print(f"\nCost estimate for {daily_volume} daily transactions, "
          f"avg {avg_amount:.0f} NIS:")
    print(f"{'Gateway':<12} {'Monthly Volume':<18} {'Fee Range':<12} "
          f"{'Min Cost':<12} {'Max Cost':<12} {'Avg Cost':<12}")
    print("-" * 80)

    costs = []
    for name, gw in gateways.items():
        cost = estimate_monthly_cost(gw, daily_volume, avg_amount)
        costs.append(cost)
        print(f"{cost['gateway']:<12} {cost['monthly_volume_nis']:>14,.0f} NIS "
              f"{cost['fee_range_pct']:<12} "
              f"{cost['monthly_fee_min_nis']:>8,.0f} NIS "
              f"{cost['monthly_fee_max_nis']:>8,.0f} NIS "
              f"{cost['monthly_fee_avg_nis']:>8,.0f} NIS")

    # מציאת השער הזול ביותר
    cheapest = min(costs, key=lambda c: c["monthly_fee_avg_nis"])
    print(f"\nLowest average cost: {cheapest['gateway']} "
          f"({cheapest['monthly_fee_avg_nis']:,.0f} NIS/month)")


def main():
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description="Compare Israeli payment gateways "
                    "(השוואת שערי תשלום ישראליים)"
    )
    parser.add_argument(
        "--features",
        help="Required features, comma-separated: "
             "installments, credit, club, recurring, bit, apple_pay"
    )
    parser.add_argument(
        "--volume", type=int,
        help="Average daily transaction count (מספר עסקאות יומי)"
    )
    parser.add_argument(
        "--avg-amount", type=float, default=200,
        help="Average transaction amount in NIS (סכום עסקה ממוצע, default: 200)"
    )
    parser.add_argument(
        "--all", action="store_true",
        help="Show all gateways comparison"
    )
    parser.add_argument(
        "--json", action="store_true",
        help="Output as JSON"
    )
    parser.add_argument(
        "--example", action="store_true",
        help="Show example comparison"
    )

    args = parser.parse_args()

    if not any([args.features, args.volume, args.all, args.example]):
        parser.print_help()
        sys.exit(1)

    gateways = GATEWAYS.copy()

    if args.example:
        print("=== All Gateways Comparison ===")
        print_comparison_table(gateways)
        print("\n=== Cost Estimate: 500 daily transactions, avg 200 NIS ===")
        print_cost_comparison(gateways, 500, 200)
        print("\n=== Gateways with Bit Support ===")
        bit_gateways = filter_by_features(gateways, ["bit"])
        print_comparison_table(bit_gateways)
        return

    # Filter by features if specified
    if args.features:
        features = args.features.split(",")
        gateways = filter_by_features(gateways, features)
        if not gateways:
            print(f"No gateways match features: {args.features}")
            sys.exit(1)

    if args.json:
        data = {name: asdict(gw) for name, gw in gateways.items()}
        if args.volume:
            for name, gw in gateways.items():
                data[name]["cost_estimate"] = estimate_monthly_cost(
                    gw, args.volume, args.avg_amount
                )
        print(json.dumps(data, indent=2, ensure_ascii=False))
    else:
        print_comparison_table(gateways)
        if args.volume:
            print_cost_comparison(gateways, args.volume, args.avg_amount)


if __name__ == "__main__":
    main()