Cardcom Payment Gateway

Overview

Cardcom is an Israeli payment processor with a unique strength: integrated invoice and receipt generation compliant with Israeli tax law. While other Israeli gateways handle only the payment, Cardcom can automatically generate tax invoices (hashbonit mas) and receipts (kabala) as part of the payment flow -- something Israeli businesses are legally required to issue.

This skill guides integration with Cardcom's REST API V11 for payments, tokenization, recurring billing, and document generation.

Official docs: Available through Cardcom developer portal (contact dev@secure.cardcom.co.il for access)

Developer support: dev@secure.cardcom.co.il or 03-9436100 (press 2)

Instructions

Step 1: Choose Integration Pattern

Pattern	Card Data Handling	Best For
Low Profile (iframe/redirect)	Cardcom handles card entry	Most integrations -- minimal PCI scope (SAQ-A)
OpenFields (embedded fields)	Card inputs hosted by Cardcom in your form	Custom UI with PCI compliance (SAQ-A)
ChargeToken (server-to-server)	Token only, no raw card data	Recurring charges, subscription billing
CreateDocument (server-to-server)	No card data	Standalone invoice/receipt generation

Most Israeli merchants use Low Profile for initial payment + token creation, then ChargeToken for recurring charges. Use OpenFields when you need full control over the checkout design. Both payment methods can auto-generate invoices.

Step 2: Set Up Authentication

Cardcom API V11 credentials:

• TerminalNumber -- Your terminal ID (use 1000 for testing)
• ApiName -- API username (use bWlyb24gY2FyZGNvbQ== for testing)
• ApiPassword -- API password

Test environment: Terminal 1000 with the test credentials allows full API testing without real charges. Test card: 4580000000000000, any future expiry, CVV 123.

Store credentials securely -- never in source code or client-side JavaScript.

Step 3: Implement the Payment Flow

Low Profile Integration (Recommended)

This is a two-step process:

Step 3a: Create the payment page

POST https://secure.cardcom.solutions/Interface/LowProfile.aspx
Content-Type: application/json

{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "ReturnValue": "unique-order-id",
  "Amount": 100.00,
  "SuccessRedirectUrl": "https://example.com/success",
  "FailedRedirectUrl": "https://example.com/failed",
  "WebHookUrl": "https://example.com/webhook",
  "Document": {
    "DocTypeToCreate": 101,
    "Name": "Customer Name",
    "Products": [
      {
        "Description": "Product name",
        "UnitCost": 100.00,
        "Quantity": 1
      }
    ]
  },
  "CoinID": 1,
  "Language": "he"
}

Response includes Url -- redirect customer there or embed as iframe.

Step 3b: Get the results

After payment completes, Cardcom calls your WebHookUrl or you query:

POST https://secure.cardcom.solutions/Interface/BillGoldGetLowProfileIndicator.aspx
{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "LowProfileCode": "code-from-step-3a"
}

Check DealResponse = 0 for success. Extract Token for future charges.

OpenFields Integration (Custom UI)

OpenFields is Cardcom's newest integration pattern (2026). It lets you build your own payment form while Cardcom-hosted iframes handle sensitive card inputs:

1. Create a Low Profile session via /Interface/LowProfile.aspx
2. Embed Cardcom's OpenFields JS on your page
3. Mount secure iframe fields for card number, expiry, and CVV inside your form
4. On submit, the JS tokenizes card data and submits to Cardcom
5. Retrieve results via BillGoldGetLowProfileIndicator.aspx

This gives full design control while maintaining SAQ-A PCI compliance. Official examples: https://github.com/CardCom (React and vanilla JS).

Alternative Payment Methods

The Low Profile response includes URLs for alternative payment methods when enabled on your terminal:

Method	Response Field	Notes
Bit	BitUrl	Israel's most popular mobile payment app
Google Pay	GooglePayUrl	For mobile and web
PayPal	PayPalUrl	International payments

Display these alongside the credit card form to give customers more payment options.

Step 4: Generate Israeli Tax Documents

Cardcom's standout feature is automatic document generation with payments. This is critical for Israeli businesses because tax law requires issuing proper documents for every transaction.

Document types (DocTypeToCreate):

Code	Hebrew	English	When to Use
1	hashbonit mas	Tax Invoice	B2B sales, services
2	hashbonit zikui	Credit Note	Refunds, corrections
3	kabala	Receipt	Payment confirmation
101	hashbonit mas / kabala	Tax Invoice + Receipt	B2C with payment (most common)
400	--	Iframe document	Low Profile context

Include document in payment flow: Add the Document object to your Low Profile or ChargeToken request (as shown in Step 3a). Cardcom generates the document automatically when payment succeeds.

Standalone document creation:

POST https://secure.cardcom.solutions/Interface/CreateDocument.aspx
{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "Document": {
    "DocTypeToCreate": 1,
    "Name": "Customer Ltd",
    "VAT_Number": "123456789",
    "Products": [
      {
        "Description": "Web development services",
        "UnitCost": 5000.00,
        "Quantity": 1,
        "IsVatFree": false
      }
    ],
    "SendByEmail": true,
    "Email": "customer@example.com",
    "Language": "he",
    "CoinID": 1
  }
}

Response includes InvoiceNumber, InvoiceType, and Link to the PDF document.

Step 5: Implement Token-Based Recurring Payments

For subscriptions and recurring billing (hora'ot keva):

1. Create token during first payment:

   • Use Low Profile with token creation enabled
   • Response includes Token, CardValidityMonth, CardValidityYear

2. Store token securely:

   • Save token (UUID format), card expiry, and last 4 digits
   • Token is bound to your terminal

3. Charge the token:

POST https://secure.cardcom.solutions/Interface/BillGoldCharge.aspx
{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "Token": "token-uuid",
  "CardValidityMonth": "12",
  "CardValidityYear": "2027",
  "Amount": 99.00,
  "Document": {
    "DocTypeToCreate": 101,
    "Name": "Subscriber Name",
    "Products": [
      {
        "Description": "Monthly subscription - February 2026",
        "UnitCost": 99.00,
        "Quantity": 1
      }
    ],
    "SendByEmail": true,
    "Email": "customer@example.com"
  }
}

Each token charge can automatically generate and email an invoice.

Step 6: Process Refunds

Refund a transaction and optionally generate a credit note:

POST https://secure.cardcom.solutions/Interface/BillGoldRefund.aspx
{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "TransactionId": "original-transaction-id",
  "Amount": 100.00,
  "Document": {
    "DocTypeToCreate": 2,
    "Name": "Customer Name"
  }
}

This both refunds the payment AND generates a credit note (hashbonit zikui) -- handling both the financial and tax compliance sides in one call.

Step 7: Handle Token Replacements (Muhlafim)

When credit cards are replaced (expired, lost, reissued), Cardcom can automatically update stored tokens:

1. Check for updated tokens periodically via GetMuhlafimByDate or GetNewMuhlafim
2. These endpoints return tokens where the underlying card was replaced by the issuer
3. Update your stored token data (new expiry, last 4 digits) in your database
4. Mark replacements as processed via UpdateMuhlafimDone

This prevents failed charges when customers receive new cards -- critical for subscription-based businesses.

Step 8: Use Suspended Deals (Deferred Payments)

Suspended deals let you authorize a payment without immediate charge:

1. Create a suspended deal via Low Profile with Operation: "SuspendDealOnly"
2. The payment is authorized but not charged
3. Activate the deal later via SuspendedDealActivateOne when ready to charge
4. Optionally cancel unused suspended deals via RevokeLowProfileDeal

Useful for pre-authorizations, hotel bookings, or services billed after delivery.

Step 9: Handle Errors

Check response codes in every API call. A response of 0 means success.

Common errors:

Code	Meaning	Action
0	Success	Proceed normally
5033	Terminal number missing	Check TerminalNumber in request
5034	Authentication failed	Verify ApiName and ApiPassword
5035	Invalid amount	Ensure Amount is positive number
5100	Card declined	Ask user to try another card
5101	Expired card	Ask user to update card details
5102	CVV incorrect	Ask user to re-enter CVV
5200	Token not found	Verify token UUID and terminal match
5300	Invoice creation failed	Check Document parameters

For the full API response reference, consult references/api-responses.md.

Examples

Example 1: E-commerce Checkout with Invoice

User says: "I need to accept payments on my Israeli e-commerce site and generate tax invoices automatically" Actions:

1. Choose: Low Profile integration with DocTypeToCreate=101 (tax invoice + receipt)
2. Guide: Create Low Profile page with product details in Document object
3. Implement: WebHook handler for payment confirmation
4. Result: Customer pays, gets automatic hashbonit mas/kabala emailed as PDF Result: Full checkout flow with automatic Israeli tax document compliance.

Example 2: Monthly SaaS Subscription

User says: "I run a SaaS product, I need to charge users 149 NIS monthly and send them invoices" Actions:

1. First payment: Low Profile with token creation
2. Store: Token, card expiry from response
3. Monthly cron: ChargeToken with Document for each billing cycle
4. Handle: Failed charges, expired cards, email invoices Result: Automated recurring billing with monthly invoice generation.

Example 3: Standalone Invoice Without Payment

User says: "I need to generate a tax invoice for a bank transfer payment I already received" Actions:

1. Use: CreateDocument endpoint (no payment processing)
2. Set: DocTypeToCreate=1 (tax invoice)
3. Include: Customer details, line items, amounts
4. Send: Set SendByEmail=true with customer email Result: Tax invoice generated and emailed without credit card processing.

Example 4: Process a Refund with Credit Note

User says: "Customer wants a refund for order #5678, need to issue a credit note too" Actions:

1. Use: RefundByTransactionId endpoint
2. Include: Document with DocTypeToCreate=2 (credit note)
3. Process: Refund + credit note generated in single API call
4. Verify: DealResponse=0 for success Result: Refund processed and hashbonit zikui (credit note) generated automatically.

Example 5: Accept Bit Payment

User says: "I want to let customers pay with Bit in addition to credit cards" Actions:

1. Enable: Bit on your Cardcom terminal via dashboard
2. Create: Low Profile session as usual
3. Display: Show the BitUrl from the response alongside the card form
4. Handle: Same webhook flow -- DealResponse=0 for success Result: Customers can choose between credit card and Bit payment.

Example 6: Custom Checkout with OpenFields

User says: "I want to design my own payment form but keep PCI compliance" Actions:

1. Create: Low Profile session to get the OpenFields token
2. Embed: Cardcom OpenFields JS and mount secure iframe fields in your form
3. Style: Apply your own CSS to the form while card inputs remain Cardcom-hosted
4. Submit: JS tokenizes and sends card data directly to Cardcom
5. Retrieve: Get results via GetLpResult Result: Fully custom checkout design with SAQ-A PCI compliance.

Community Libraries

• @tsdiapi/cardcom (TypeScript/Node.js) -- API V11 client with payments, refunds, tokenization, transaction queries. Install: npm install @tsdiapi/cardcom
• yadahan/laravel-cardcom (PHP/Laravel) -- Full integration with charges, refunds, tokens, invoices, multi-terminal
• CardCom/OpenFields-FrontEnd-React (React) -- Official React OpenFields example. See: https://github.com/CardCom/OpenFields-FrontEnd-React
• CardCom/OpenFields-Backend-Node (Node.js) -- Official Node.js backend example

Bundled Resources

References

• references/api-endpoints.md -- Complete Cardcom REST API V11 endpoint reference including Low Profile, Transactions, Documents, RecurringPayments, Financial, and CompanyOperations. Lists request/response fields for each endpoint. Consult when building API integrations or exploring available operations.
• references/api-responses.md -- Full listing of Cardcom response codes with meanings and recommended handling for transaction, token, and invoice operations. Consult when debugging failed API calls.
• references/document-types.md -- Israeli tax document type codes (1, 2, 3, 101, 400) with required fields, VAT handling, and usage guidelines per Israeli tax law. Consult when determining which document type to generate for a transaction.

Scripts

• scripts/validate_cardcom_response.py -- Validates a Cardcom API response: checks response codes for transaction, token, and invoice operations, verifies required fields, and flags common integration issues. Run: python scripts/validate_cardcom_response.py --help

Gotchas

• Agents often send Cardcom API requests as application/json, but the V11 API expects JSON with a Content-Type: application/json header. Older Cardcom APIs used form-encoded data, so agents trained on older examples may use the wrong format.
• The TerminalNumber must be sent as an integer, not a string. Agents commonly wrap it in quotes, causing error 5033.
• Agents may hardcode VAT at 17%, but the current Israeli VAT rate is 18% (effective January 2025). Cardcom calculates VAT server-side, so the Document amounts should be net of VAT unless specified otherwise.
• Cardcom's test terminal (1000) does not support all features available in production. Agents may write integration tests that pass in sandbox but fail in production due to terminal-specific configurations.

Troubleshooting

Error: "5033 -- Terminal Number is Missing"

Cause: TerminalNumber not included or sent as wrong type Solution: Ensure TerminalNumber is sent as an integer (not string) in the JSON body. For testing, use 1000.

Error: "5034 -- Authentication failed"

Cause: Invalid ApiName or ApiPassword Solution: Verify credentials in your Cardcom dashboard. For testing, use terminal 1000 with the test API credentials. Credentials are separate from your login password.

Error: "Low Profile page loads but payment fails"

Cause: Often a WebHookUrl or redirect URL issue Solution: Ensure SuccessRedirectUrl, FailedRedirectUrl, and WebHookUrl are publicly accessible HTTPS URLs. Localhost URLs do not work -- use a tunnel (ngrok) for development.

Error: "Invoice created but not emailed"

Cause: SendByEmail not set or email address missing Solution: Set SendByEmail: true and include a valid Email in the Document object. Check spam folders -- Cardcom sends from their domain.

Error: "Token charge succeeds but no invoice"

Cause: Document object missing from ChargeToken request Solution: Include the full Document object with DocTypeToCreate, Name, and Products in every token charge request. Document generation is opt-in per transaction, not automatic.