Israeli Payment Orchestrator

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

# 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 only to Cardcom/Pelecard | | 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:

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:

# 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://grow-il.readme.io/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.

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skills-il
• Source: skills-il/tax-and-finance
• License: MIT

Install and usage instructions live in the source repository linked above.