israeli-payment-orchestrator

---
name: israeli-payment-orchestrator
description: 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).
license: MIT
---

# Israeli Payment Orchestrator

## Instructions

### Step 1: Assess Payment Requirements
Ask the user about their payment needs:

| Requirement | Hebrew | Description | Impact on Gateway Choice |
|-------------|--------|-------------|-------------------------|
| Installments (tashlumim) | תשלומים | Split payment into monthly installments | Not all gateways support all installment types |
| Recurring billing | חיוב חוזר | Subscription / standing order | Requires token storage and Shva approval |
| Multi-currency | רב-מטבעי | Accept NIS + foreign currencies | Limited gateway support for dual currency |
| Iframe / redirect | דף סליקה | Hosted payment page vs embedded | Affects PCI scope |
| Bit / Apple Pay | ביט / אפל פיי | Alternative payment methods | Gateway-specific integrations |
| High volume | נפח גבוה | Over 1,000 transactions/day | Need SLA guarantees and fallback |

### Step 2: Compare Gateways
Use `scripts/compare_gateways.py` to generate a comparison matrix, or reference the table below:

| Gateway | API Style | Installments | Recurring | Hosted Page | Bit Support | Typical Fee |
|---------|-----------|-------------|-----------|-------------|-------------|-------------|
| Cardcom | REST JSON | Full (regular, credit, club) | Yes | Yes (iframe) | No | 0.6-0.8% |
| Tranzila | REST/Form POST | Regular, credit, club | Yes | Yes (redirect) | No | 0.5-0.7% |
| PayMe | REST JSON | Regular, credit | Yes | Yes (iframe) | Yes | 0.7-1.0% |
| Meshulam | multipart/form-data | Regular | Yes | Yes (iframe + redirect) | Yes | 0.6-0.9% |
| iCredit | REST JSON | Regular, credit | Yes | Yes (redirect) | No | 0.5-0.8% |
| Pelecard | REST JSON | Regular, credit, club | Yes | Yes (iframe) | No | 0.5-0.7% |

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:

```python
# 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:

| Rule | Priority | Logic | Example |
|------|----------|-------|---------|
| Cost optimization | Medium | Route to cheapest gateway for transaction type | Small payments to lowest-fee gateway |
| Feature match | High | Route based on required features | Club installments (cred_type 9) to Cardcom, Pelecard, or Tranzila |
| Availability | Critical | Route away from failed/degraded gateways | If Tranzila is down, failover to Cardcom |
| Volume balancing | Low | Distribute load across gateways | 60/40 split between primary and secondary |
| Card type | High | Some gateways handle specific cards better | Diners Club routing |

Routing logic:
```python
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. The numbers below are the Shva **CreditType** (סוג אשראי) values, a field distinct from the transaction type (סוג עסקה). The canonical CreditType enum is: 1=regular/immediate, 2=Isracredit/30+, 3=immediate debit, 4=club credit, 5=Leumi special, 6=credit (קרדיט), 8=installments (תשלומים), 9=club installments.

| Type | Hebrew | CreditType | How It Works | Who Pays Interest |
|------|--------|-----------|--------------|-------------------|
| Regular installments | תשלומים רגילים | 8 | Merchant gets full amount upfront, bank collects from customer monthly | Customer (no interest by default) |
| Credit installments | קרדיט | 6 | Customer pays bank in installments with interest, merchant gets full amount | Customer pays interest to bank |
| Club installments | מועדון | 9 | Issuer-specific program (Isracard, CAL, Max); club credit is 4 | Varies by program |
| "Payments without interest" | תשלומים ללא ריבית | 8 | Merchant subsidizes interest cost | Merchant absorbs cost |

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:

```python
# 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:

| Regulation | Hebrew | Requirement | Impact |
|------------|--------|-------------|--------|
| Transaction data retention | שמירת נתוני עסקאות | Transaction data retention, reporting | Store all transaction details 7 years |
| PCI DSS | תקן PCI | Card data security | Use tokenization, never store full card numbers |
| Shva regulations | תקנות שב"א | Clearing and settlement rules | Adhere to clearing windows and dispute timelines |
| Consumer Protection | הגנת הצרכן | Refund rights, clear pricing | Display installment terms clearly |
| Anti-fraud | מניעת הונאה | 3D Secure, velocity checks | Implement 3DS2 for CNP transactions |

## Examples

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

## Bundled Resources

### 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.

## Reference Links

| Source | URL | What to Check |
|--------|-----|---------------|
| Cardcom | https://www.cardcom.co.il/ | Current API surface, pricing, supported card types |
| Tranzila Documentation | https://docs.tranzila.com/ | Form-encoded API parameters, supplier code (terminalname) flows |
| PayMe Developer Docs | https://www.payme.io/developers | Bearer-token REST JSON API, Bit/Apple Pay support |
| Meshulam (Grow) Reference | https://developers.grow.business/reference/overview | Production base = secure.meshulam.co.il (do NOT use sandbox.meshulam.co.il in prod) |
| iCredit | https://icredit.rivhit.co.il/ | Group private token + credentials auth scheme |
| Bank of Israel: Payment Systems Oversight | https://www.boi.org.il/en/economic-roles/supervision-and-regulation/payment-systems-oversight/ | BOI oversight of Shva and controlled payment systems (banks + credit-card companies). Non-bank payment-service providers are regulated by the ISA under the Regulation of Payment Services and Payment Initiation Law 5783-2023 |

## Gotchas
- Each Israeli payment gateway in this skill (Cardcom, Tranzila, PayMe, Meshulam, iCredit, Pelecard) has a completely different API format: Cardcom uses JSON, Tranzila uses form-encoded key-value pairs, Meshulam uses multipart/form-data with a separate page-code parameter, and PayMe uses bearer-token JSON. Agents may apply one gateway's format to another.
- Israeli payment processing requires Israeli business registration (osek murshe/patur). Agents may suggest setting up payment processing before verifying the business has proper registration with the Tax Authority.
- PCI DSS compliance requirements in Israel follow the same international standard, but Israeli acquirers (Isracard, Visa CAL) may have additional local requirements. Agents may generate PCI-compliant code that misses Israeli acquirer-specific fields.
- Bit (Israel's dominant mobile payment) refunds use a different API endpoint than credit card refunds on most gateways. Agents may use the credit card refund endpoint for Bit transactions.
- **Saved-card tokens are NOT portable across gateways.** A Cardcom token, a Tranzila `TranzilaTK`, and a PayMe `buyer_key` are proprietary and mutually incompatible, each usable only on the gateway that issued it. This means the fallback/failover pattern in this skill applies to first-charge and one-time transactions only. A tokenized or recurring charge cannot fail over to a second gateway, recurring billing is pinned to its originating gateway. True cross-gateway resilience for saved cards requires network tokenization or a multi-vault strategy, not this token field. Agents may wrongly assume a stored token works on any gateway in the priority list.
- **A gateway's client-side "success" is spoofable, always re-verify server-side.** Do not trust the browser redirect or a client-posted status as proof of payment. Confirm every transaction with a server-to-server query to the issuing gateway (for Meshulam/Grow, `getPaymentProcessInfo`/approve; for others, the gateway's transaction-lookup or webhook-signature/notify verification) before fulfilling the order. Webhook/IPN payloads must be authenticated per each gateway's scheme, they are not interchangeable.
- **3DS2 is an asynchronous challenge flow, not a single call.** A card-not-present charge may return "frictionless" (approved inline) or trigger a challenge that redirects the customer to the issuer and returns via a callback URL. The orchestrator must persist the transaction, resume on the callback, and keep the challenge return on the SAME gateway that started it (the 3DS session is gateway-scoped). Agents may model 3DS as a synchronous boolean and lose challenged transactions.

## Troubleshooting

### 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 (Shva CreditType 9) are supported on Cardcom, Pelecard, and Tranzila (the Visa/Diners card-network restriction on cred_type 9 applies identically across gateways, so it is not a gateway limitation). Route to a gateway whose terminal is configured for the club program.

### 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.