cardcom-payment-gateway

Cardcom Payment Gateway

Legal notice

This is a free technical integration guide operated by an AI model. It explains how to call the Cardcom API and how the Israeli invoicing rules bear on it. All of its outputs are produced automatically by an AI model, with no involvement, review, or approval by a tax adviser, accountant, or lawyer. Nothing here is a tax opinion or professional advice, and an AI model may err, omit data, or present a wrong conclusion.

The documents this integration produces are tax documents. Responsibility for issuing them correctly, for reporting, and for paying the tax is yours, the binding computation is the Tax Authority's, and representation before the Tax Authority is reserved to those permitted by law. Whether a given invoice requires an allocation number, and whether input VAT may be deducted, are determinations for your accountant on your actual facts. Have a tax adviser or accountant review the invoicing configuration before you go live, and handle cardholder data in accordance with PCI DSS. All use of this skill's output is the user's sole responsibility.

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. Every endpoint and field name in this skill is taken from the official Cardcom V11 OpenAPI specification.

Official docs: https://secure.cardcom.solutions/Api/v11/Docs (interactive API reference with the full OpenAPI schema). V11 is the current API as of 2026; there is no public V12.

Support center: https://support.cardcom.solutions

Cardcom in the Israeli landscape: competes with Tranzila, Israpay, and Bit Business. Pricing is quoted per merchant. Cardcom publishes a starting rate of about 1.2% that falls with volume, but that is a floor and not a quote, so treat it as a starting point only and send the user to Cardcom for an actual figure rather than promising them a rate. The distinguishing feature for Israeli businesses remains the built-in tax document generation. For Tranzila integration use the tranzila-payment-gateway skill instead.

Instructions

Step 1: Choose Integration Pattern

Most Israeli merchants use Low Profile for the initial payment plus token creation, then the Transaction endpoint with the stored token for recurring charges. All payment flows can auto-generate invoices by attaching a Document object.

Step 2: Set Up Authentication

Cardcom API V11 credentials:

• TerminalNumber (integer) -- your terminal ID (use 1000 for testing)
• ApiName (string) -- API username
• ApiPassword (string) -- API password. Required on roughly half the V11 request schemas (26 of the 219 component schemas list it in required as of the current spec; the count moves between spec revisions, so read the schema rather than trusting a number). The rule of thumb: operations that read or act on company-wide data require it; operations that charge a single card do not. It is required on every Documents/* write, every Financial/* report, every TapTransactions/* call, and on Transactions/ListTransactions, RefundByTransactionId, and SpecialTransactions. It is NOT a field on LowProfile/Create or Transactions/Transaction at all, so do not send it there. When in doubt, check the required array for the endpoint's request schema in the V11 OpenAPI spec.

Test environment: Terminal 1000 with the demo ApiName is widely cited in community libraries as the sandbox, with test card 4580000000000000, any future expiry, CVV 123. We have NOT been able to confirm these against an official Cardcom test-credentials page, so treat them as community folklore: confirm your sandbox credentials with Cardcom support before relying on them, and never assume a call against terminal 1000 cannot move money.

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/api/v11/LowProfile/Create
Content-Type: application/json

{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "Operation": "ChargeAndCreateToken",
  "ReturnValue": "unique-order-id",
  "Amount": 100.00,
  "SuccessRedirectUrl": "https://example.com/success",
  "FailedRedirectUrl": "https://example.com/failed",
  "WebHookUrl": "https://example.com/webhook",

The response is a CreateLowProfileResponse: check ResponseCode == 0 (success), read Description on failure. On success it returns LowProfileId (save it) and Url (redirect the customer there or embed as an iframe). UrlToBit and UrlToPayPal are also returned when those methods are enabled on your terminal.

The Operation field controls behaviour: ChargeOnly (default), ChargeAndCreateToken, CreateTokenOnly, SuspendedDeal, Do3DSAndSubmit.

Step 3b: Get the results

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

The response is a LowProfileResult, and its top-level ResponseCode is NOT the payment result. The spec describes it as "if equel zero then success , else , a develper error" -- it tells you the request was well formed, nothing more. The card result lives in the nested TranzactionInfo, which the spec says "Will no be null at operations: ChargeOnly, ChargeAndCreateToken", i.e. it is null when the cardholder abandoned the page.

Before fulfilling anything, all five of these must hold:

1. HTTP status is 200. A 404 returns {"Message": "No HTTP resource was found..."} with no ResponseCode at all, so branching on ResponseCode == 0 alone reads a routing error as None.
2. Top-level ResponseCode == 0.
3. TranzactionInfo is non-null.
4. TranzactionInfo.ResponseCode == 0 (its own description: "if equal zero then success , 700 and 701 success for J2 and J5 transaction").
5. TranzactionInfo.Amount equals the amount you expected, and ReturnValue matches your own order id.

Also check TranzactionInfo.IsRefund / DealType: a refund is a successful transaction and will pass a naive ResponseCode == 0 test. If you asked for a document, DocumentInfo must be non-null too -- a charge that succeeded with DocumentInfo: null means you took the money and never issued the tax invoice. scripts/validate_cardcom_response.py --expect charge --amount <n> applies all of this and fails closed.

Never fulfil on the browser landing at SuccessRedirectUrl, which the customer controls, or on the raw webhook body, which is an unauthenticated public POST. Treat the webhook only as a signal to call GetLpResult and re-check. TokenInfo carries the stored Token plus CardMonth/CardYear; SuspendedInfo covers suspended deals.

Alternative Payment Methods

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

UrlToBit and UrlToPayPal are explicit URL fields you can show alongside the card form. Apple Pay and Google Pay surface as wallet buttons inside the hosted Low Profile page itself once enabled on the terminal, so no separate URL field is exposed. Enable each method on your terminal in the Cardcom admin panel before relying on it in production.

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.

The document type is set with the DocumentTypeToCreate field, a STRING enum (not an integer). Common values:

The full DocumentToCreate enum has 25 values and also includes Quote, Order, OrderConfirmation, DeliveryNote, DemandForPayment, ProformaDealInvoice, ReceiptForTaxInvoice and CouponDocumentAndReceipt. Refund variants exist for MOST but not all of these: there is no QuoteRefund and no OrderRefund. The 11 that do exist are TaxInvoiceAndReceiptRefund, ReceiptRefund, OrderConfirmationRefund, DeliveryNoteRefund, DemandForPaymentRefund, ProformaDealInvoiceRefund, ProformaInvoiceRefund, TaxInvoiceRefund, DonationReceiptRefund, CouponDocumentAndReceiptRefund and ReceiptForTaxInvoiceRefund. Verify the exact value you need against the official docs at https://secure.cardcom.solutions/Api/v11/Docs.

Include a document in a payment flow: Add the Document object to your Low Profile Create or Transaction request. Cardcom generates the document automatically when the payment succeeds.

Standalone document creation:

The response is a DocumentInfo: check ResponseCode == 0, then read DocumentType, DocumentNumber, AccountId, and DocumentUrl (link to the PDF).

Note the real V11 field spellings inside the Document object: DocumentTypeToCreate (string enum), Name (the "document To", required, max 50 chars), TaxId (business registration or ID number, replaces the older VAT_Number), IsSendByEmail (replaces SendByEmail), Languge (the V11 spelling in THIS schema, missing the second a; note that the Low Profile document object DocumentLP uses the correctly spelled Language instead), ISOCoinID (replaces CoinID), IsVatFree, and Products[] with Description, UnitCost, Quantity, IsVatFree. See references/document-types.md for the complete field list.

Step 4.5: Allocation Numbers (Mispar Haktzaa) on Tax Invoices

Do not look for an allocation-number field in the API. There isn't one, and that is not an omission. Cardcom built a direct interface to the Tax Authority, so when you issue a tax invoice over the threshold the allocation number is requested automatically at document creation, server-side. The CreateDocument request body carries no AllocationNumber field, and a developer hunting for one in the OpenAPI spec will conclude, wrongly, that Cardcom does not support the requirement.

It is not on by default. It needs a one-time setup, and without it your customer cannot deduct their input VAT. An allocation number on a tax invoice is a precondition for the recipient to deduct input VAT on any invoice whose pre-VAT amount exceeds the statutory threshold. The setup, done once by the business owner or director on the Tax Authority site, is:

1. Identify (הזדהות) in the Tax Authority personal area, registering if necessary.
2. For a company or a VAT-registered group (איחוד עוסקים), complete corporation registration (רישום פרטי תאגיד).
3. In the Tax Authority digital-actions authorization system (מערכת הרשאה לפעולות דיגיטליות, linked from the ITA allocation-number service page), grant the authorization and select BOTH Israel-Invoice subjects, not one of them. One covers verifying the allocation number on a supplier's invoice; the other covers requesting an allocation number for an invoice you issue to a customer. Granting only the first is the common mistake, and it leaves your own invoices without a number. The exact wording of the two subjects is only visible inside that system, which is behind a login, so match them by meaning rather than by a string quoted here.
4. Choose the authorization duration, and have the grantee confirm it.

Threshold schedule (amounts are pre-VAT):

The allocation-number requirement began in May 2024.

Invoices dated before May 2024 predate the regime and never needed a number. The threshold is keyed to the DOCUMENT's own date, so if you are reissuing, migrating or auditing older documents, test each against the threshold in force on its date rather than today's 5,000. The statute says עולה על (EXCEEDS), so a document exactly at the threshold is outside it.

An osek patur is unaffected, because they do not issue tax invoices and do not deduct input VAT. Zero-rated and exempt-only invoices are also outside the requirement (s.47(a2)(1)), so an export invoice does not need a number however large. If an integration was written earlier in 2026 against the 10,000 figure, invoices between 5,000 and 10,000 are the band to re-check.

Step 4.6: Idempotency, and Authorize vs Capture

Send ExternalUniqTranId on every Transactions/Transaction call. It is your own unique id for the charge, and the spec is explicit: "send your uniq trnasaction id to prevent duplication of transaction. if the same ExternalUniqTranId will be send you will receive and error code 608". Without it, a cron whose HTTP call times out AFTER Cardcom charged the card retries and charges the customer twice.

608 means "already charged", not "payment failed". It is the one error code you must special-case: treat it as a duplicate that was correctly blocked, not as a failure to retry or to re-charge manually. After any timeout or ambiguous result, call POST /api/v11/Transactions/GetTransactionByExternalUniqTran to find out whether the original charge actually went through before doing anything else.

J2 and J5 are not the same thing, and 700/701 do not mean the customer is untouched. Advanced.JValidateType selects J2 (a simple card validation, nothing reserved) or J5 (an authorization, which HOLDS the funds on the cardholder's limit). A J5 must then be captured with Advanced.ApprovalNumber, documented in the spec as "capture an J5 (authoriz) request". An authorization that is never captured leaves the customer's money held until it expires, so if you use J5 you must have a capture step and a release path.

Step 5: Implement Token-Based Recurring Payments

For subscriptions and recurring billing (hora'ot keva), Cardcom supports two flavours:

• Card-based recurring, charging a stored credit-card Token on a schedule. Covered in this step.
• MASAV bank standing orders, debiting the customer's Israeli bank account directly. Managed through the RecuringPayments endpoints (RecuringPayments/GetRecurringPayment, GetRecurringPaymentHistory, IsBankNumberValid). Use this when the customer prefers a bank debit over a card charge or when the card is unavailable. The Cardcom dashboard provisions the underlying instruction.

For card-based recurring:

1. Create a token during the first payment. Use Low Profile with Operation: "ChargeAndCreateToken" (or "CreateTokenOnly"). The LowProfileResult returns TokenInfo with Token, CardMonth, CardYear, and TokenExDate (the date the token is purged from Cardcom).

2. Store the token securely. Save the Token string, card expiry, and last 4 digits. The token is bound to your terminal.

3. Charge the token via the Transaction endpoint:

The response is a TransactionInfo: check ResponseCode == 0 (note 700 and 701 also count as success for J2/J5 validation-only transactions), then read TranzactionId, Token, DocumentNumber, and DocumentUrl. Each token charge can automatically generate and email an invoice when a Document object is attached.

Step 6: Process Refunds

Refund a transaction by its Cardcom transaction id:

ApiPassword is required for refunds. PartialSum refunds part of the transaction (omit it to refund the full amount). CancelOnly: true voids a transaction before it is deposited. The response is a RefundByTransactionIdResp: check ResponseCode == 0, then read NewTranzactionId (the id of the refund transaction).

To issue the matching credit document, call Documents/CreateDocument with a refund DocumentTypeToCreate such as TaxInvoiceAndReceiptRefund or TaxInvoiceRefund.

Step 6.5: Query Transactions for Reporting

To pull a date range of transactions (reconciliation, monthly reports, dashboards):

Four things about this endpoint trip up almost every integration:

1. ApiPassword is required. This is a company-wide read, not a single charge.
2. There is no TerminalNumber field. The schema sets additionalProperties: false, so sending TerminalNumber is rejected outright. To scope results to one terminal, use the optional LimitForTerminal instead.
3. Dates are DDMMYYYY strings, not ISO. 01062026 is 1 June 2026.
4. Page and Page_size are both required, and Page_size must be between 10 and 2000. Paging starts at 1, not 0.

The response is a GetTranzactionsResp: check ResponseCode == 0, then read Tranzactions (an array of TransactionInfo), plus the echoed Page and Page_size. Keep requesting the next page until a page returns fewer rows than Page_size.

Transactions/SpecialTransactions is a sibling read endpoint (it returns other transactions when Cardcom is your acquirer) and takes exactly the same four required fields: ApiName, ApiPassword, FromDate, ToDate. Despite the name, it does not create anything.

Step 7: Suspended Deals (Deferred Charges)

A suspended deal authorizes a payment intent without an immediate charge:

1. Create a Low Profile session with Operation: "SuspendedDeal".
2. The LowProfileResult returns SuspendedInfo with a SuspendedDealId.
3. Charge the suspended deal later through the Cardcom admin panel or the SuspendedDeals/Charge endpoint (the SuspendedDeals group also exposes Cancel and GetSuspendedDealInfo).

Useful for pre-authorizations and services billed after delivery. Verify the exact SuspendedDeals/Charge request fields against the official docs before wiring the charge-later call.

Step 8: Handle Errors

Every V11 endpoint returns a ResponseCode integer and a Description string. ResponseCode == 0 means success; any non-zero value is a developer/transaction error and Description carries the human-readable reason.

Always check both the HTTP status (200 means the request was received) AND ResponseCode (0 means the operation succeeded). The official docs at https://secure.cardcom.solutions/Api/v11/Docs carry the full numeric error reference; do not hardcode error-code-to-message mappings, read Description instead. See references/api-responses.md for the handling pattern.

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 with DocumentTypeToCreate: "TaxInvoiceAndReceipt".
2. Create the Low Profile page via LowProfile/Create with product details in the Document object.
3. Implement a WebHookUrl handler that calls LowProfile/GetLpResult. Result: Customer pays and receives an automatic hashbonit mas/kabala emailed as a PDF.

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: LowProfile/Create with Operation: "ChargeAndCreateToken".
2. Store the Token, CardMonth, CardYear from TokenInfo.
3. Monthly cron: Transactions/Transaction with the token, a fresh ExternalUniqTranId per billing cycle, and a Document object. 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 Documents/CreateDocument (no payment processing).
2. Set DocumentTypeToCreate: "TaxInvoice".
3. Include Name, TaxId, Products[], set IsSendByEmail: true with the 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. Call Transactions/RefundByTransactionId with TransactionId and ApiPassword.
2. Check ResponseCode == 0 and read NewTranzactionId.
3. Call Documents/CreateDocument with DocumentTypeToCreate: "TaxInvoiceAndReceiptRefund". Result: Refund processed and the matching credit document generated.

Example 5: Accept Bit, Apple Pay, and Google Pay

User says: "I want to let customers pay with Bit, Apple Pay, and Google Pay in addition to credit cards" Actions:

1. Enable each method (Bit, Apple Pay, Google Pay) on your Cardcom terminal via the dashboard.
2. Create a Low Profile session as usual via LowProfile/Create.
3. Display UrlToBit from the response alongside the card form. Apple Pay and Google Pay surface as wallet buttons inside the Low Profile page itself, no extra URL needed. Result: Customers can choose between credit card, Bit, Apple Pay, and Google Pay, same webhook flow.

Community Libraries

• @tsdiapi/cardcom (TypeScript/Node.js) -- V11 API client with payments, refunds, tokenization, transaction queries. Install: npm install @tsdiapi/cardcom
• CardCom/OpenFields-FrontEnd-React (React) -- official OpenFields example. See https://github.com/CardCom/OpenFields-FrontEnd-React
• CardCom/OpenFields-Backend-Node (Node.js) -- official Node.js backend example. See https://github.com/CardCom/OpenFields-Backend-Node

Reference Links

Bundled Resources

References

• references/api-endpoints.md -- Cardcom REST API V11 endpoint reference: LowProfile, Transactions, Documents, RecuringPayments, Financial, and CompanyOperations paths with their key request/response fields. Consult when building API integrations.
• references/api-responses.md -- the V11 ResponseCode + Description response pattern, the per-operation response objects, and the recommended error-handling flow. Consult when debugging failed API calls.
• references/document-types.md -- the DocumentTypeToCreate string enum, the Document object field list, and VAT handling per Israeli tax law. Consult when determining which document type to generate.

Scripts

• scripts/validate_cardcom_response.py -- Validates a Cardcom V11 API response: checks ResponseCode, surfaces Description, and verifies expected fields for transaction, token, and document operations. Only ResponseCode 0 counts as success; 700/701 are rejected unless you pass --validation-only, because they mean a J2/J5 card check passed and NO money moved. Run: python scripts/validate_cardcom_response.py --help

Gotchas

• The V11 success check is ResponseCode == 0, NOT DealResponse == 0. DealResponse does not exist in V11; agents trained on older Cardcom examples invent it. Every V11 endpoint returns ResponseCode plus a Description string.
• DocumentTypeToCreate is a STRING enum ("TaxInvoiceAndReceipt", "TaxInvoice", "Receipt", ...), not an integer code. Integer document codes like 101 or 400 belong to legacy .aspx interfaces, not V11.
• The TerminalNumber must be sent as an integer, not a string. Agents commonly wrap it in quotes.
• ApiPassword is required on far more than refunds and documents: 26 request schemas list it in required in the current spec. Do NOT generalise it to a whole path family, because the exceptions are real: Documents/ExternalShopCreateDocument has no ApiPassword property at all, and Documents/CrossDocument and TapTransactions/NotifyExternalTapTransaction declare no required array. Check the schema for the exact endpoint. One case runs the other way: ApiPassword is not a TOP-LEVEL property of LowProfile/Create or Transactions/Transaction, but it IS required INSIDE the nested Advanced / AdvancedDefinition object when you set IsRefund (Transaction) or IsRefundDeal (LowProfile) -- the spec says "Required only if 'IsRefund' is true". That nested refund path is the second way to refund, used when you have a token or card but no original TransactionId. Company-wide reads and writes need it (ListTransactions, SpecialTransactions, RefundByTransactionId, all Documents/* writes, all Financial/* reports, all TapTransactions/*); single-card charges do not. It is not even a property on LowProfile/Create or Transaction, so sending it there is wrong too. Agents routinely omit it on ListTransactions because older guidance described it as "refunds and documents only".
• The reporting endpoints ListTransactions and SpecialTransactions do NOT accept TerminalNumber, and both set additionalProperties: false, so including it fails the call. Scope to a terminal with LimitForTerminal on ListTransactions. Their dates are DDMMYYYY strings, and ListTransactions additionally requires Page plus a Page_size between 10 and 2000.
• Watch the real V11 field spellings: ISOCoinID / ISOCoinId, IsSendByEmail (not SendByEmail), TaxId (not VAT_Number). The language field is spelled differently depending on which document object you are in, and every one of these schemas rejects unknown properties, so getting it wrong fails the call outright: Document (standalone CreateDocument) and DocumentTran (Transaction) use the misspelled Languge, while DocumentLP, the document you attach to LowProfile/Create, uses the correctly spelled Language. Applying Languge everywhere breaks the Low Profile flow, which is the flow this skill recommends first.
• The current Israeli VAT rate is 18% (effective January 2025; it was 17% before that, so a document reissued for an earlier period must use the rate in force on ITS date). Cardcom calculates VAT server-side, so document amounts are treated per the IsVatFree flag.
• PCI scope: hosted Low Profile keeps you in SAQ-A. Server-to-server Transaction with raw CardNumber/CVV2 lands in SAQ-D. The current standard is PCI DSS v4.0.1 (a limited revision published June 2024), and the 51 future-dated requirements became effective 31 March 2025, so all of them are now in force. Prefer Low Profile or tokens unless you have a real reason to touch raw card data.
• Settlement timing is configured on the terminal, not per request, and is not settable via the API. Cardcom publishes three cycles: monthly (transactions from the 1st through the day before month-end are credited on the 6th of the following month), weekly (Sunday through Friday, credited the Wednesday of the following week), and bi-monthly (the 1st to the 15th credited on the 2nd of the following month; the 16th through the day before month-end credited on the 8th). Still confirm the cycle actually configured on the merchant's terminal before promising a business a specific day.
• Apple Pay and Google Pay don't have separate URL fields like UrlToBit / UrlToPayPal. They surface as wallet buttons inside the hosted Low Profile page once enabled on the terminal in the admin panel.

Troubleshooting

Error: a non-zero ResponseCode on LowProfile/Create

Cause: a validation or authentication problem with the request. Solution: Read the Description string in the response, it names the exact issue. Verify TerminalNumber is an integer and ApiName is correct. The full numeric error reference is at https://secure.cardcom.solutions/Api/v11/Docs.

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: "Refund returns a non-zero ResponseCode"

Cause: ApiPassword missing, or the transaction is already deposited and you sent CancelOnly: true. Solution: Include ApiPassword on every refund request. Use CancelOnly: true only before deposit; after deposit, send a real refund (omit CancelOnly or set it false).

Error: "Invoice created but not emailed"

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

Error: "Token charge succeeds but no invoice"

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