Cardcom Payment Gateway

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. 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. Cardcom's pricing in 2026 is roughly 1.2-1.4% per transaction with optional monthly plans starting around 59 NIS/month for the invoicing add-on; exact numbers are quoted per merchant. 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 only for refunds and document creation; not sent on a normal charge)

Test environment: Terminal 1000 with the demo ApiName allows 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/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",
  "ISOCoinId": 1,
  "Language": "he",
  "Document": {
    "DocumentTypeToCreate": "TaxInvoiceAndReceipt",
    "Name": "Customer Name",
    "Email": "customer@example.com",
    "Products": [
      { "Description": "Product name", "UnitCost": 100.00, "Quantity": 1 }
    ]
  }
}

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:

POST https://secure.cardcom.solutions/api/v11/LowProfile/GetLpResult
{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "LowProfileId": "id-from-step-3a"
}

The response is a LowProfileResult: check ResponseCode == 0. On success it carries TranzactionInfo (transaction details), TokenInfo (the stored Token plus CardMonth/CardYear), DocumentInfo (the generated document), and SuspendedInfo (for suspended deals). Each nested object is null when not applicable.

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 enum (DocumentToCreate in the OpenAPI schema) also includes Quote, Order, OrderConfirmation, DeliveryNote, DemandForPayment, ProformaDealInvoice, ReceiptForTaxInvoice, CouponDocumentAndReceipt, and their *Refund variants. 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:

POST https://secure.cardcom.solutions/api/v11/Documents/CreateDocument
{
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "Document": {
    "DocumentTypeToCreate": "TaxInvoice",
    "Name": "Customer Ltd",
    "TaxId": "123456789",
    "Email": "customer@example.com",
    "IsSendByEmail": true,
    "Languge": "he",
    "ISOCoinID": 1,
    "Products": [
      { "Description": "Web development services", "UnitCost": 5000.00, "Quantity": 1 }
    ]
  }
}

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 official V11 field spelling, missing the second a), ISOCoinID (replaces CoinID), IsVatFree, and Products[] with Description, UnitCost, Quantity, IsVatFree. See references/document-types.md for the complete field list.

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:

POST https://secure.cardcom.solutions/api/v11/Transactions/Transaction
{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "Token": "token-uuid",
  "CardExpirationMMYY": "1227",
  "Amount": 99.00,
  "ISOCoinId": 1,
  "Document": {
    "DocumentTypeToCreate": "TaxInvoiceAndReceipt",
    "Name": "Subscriber Name",
    "Email": "customer@example.com",
    "IsSendByEmail": true,
    "Products": [
      { "Description": "Monthly subscription", "UnitCost": 99.00, "Quantity": 1 }
    ]
  }
}

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:

POST https://secure.cardcom.solutions/api/v11/Transactions/RefundByTransactionId
{
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "TransactionId": 219282004,
  "PartialSum": 100.00,
  "CancelOnly": false,
  "AllowMultipleRefunds": false
}

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

Useful for pre-authorizations and services billed after delivery. The exact charge-later call is described in the official docs.

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.

import requests

resp = requests.post(
    "https://secure.cardcom.solutions/api/v11/Transactions/Transaction",
    json=payload,
).json()

if resp.get("ResponseCode") == 0:
    deal_id = resp["TranzactionId"]
else:
    log_error(f"Cardcom error {resp.get('ResponseCode')}: {resp.get('Description')}")

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 and a Document object for each billing cycle. 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. 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 for RefundByTransactionId and CreateDocument, but is NOT sent on a normal LowProfile/Create or Transaction charge.
• Watch the real V11 field spellings: Languge (missing the second a) inside the Document object, ISOCoinID / ISOCoinId, IsSendByEmail (not SendByEmail), TaxId (not VAT_Number).
• The current Israeli VAT rate is 18% (effective January 2025; the January 2026 budget proposal to raise it to 19% was rejected). 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. PCI DSS v4.0 became mandatory March 2025, so 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. Weekly settlement deposits on the Wednesday following the transaction; monthly settlement deposits on the 6th of the following month. Don't try to set this in the API.
• 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.

Cardcom REST API V11 Endpoint Reference

All endpoint paths, request fields, and response fields below are taken from the official Cardcom V11 OpenAPI specification at https://secure.cardcom.solutions/Api/v11/Docs.

Base URL & Authentication

• Base: https://secure.cardcom.solutions/api/v11/
• Auth fields: TerminalNumber (integer) + ApiName (string) on every request.

ApiPassword (string) is required only for refunds and document creation.

• Test terminal: 1000 with the demo ApiName. Test card: 4580000000000000.
• Method: All endpoints are POST with Content-Type: application/json

(except a few RecuringPayments / CompanyOperations lookups that are GET).

• Response shape: Every response carries ResponseCode (integer, 0 = success)

and Description (string explaining the code).

LowProfile (Hosted Payment Page)

Operation enum: ChargeOnly (default), ChargeAndCreateToken, CreateTokenOnly, SuspendedDeal, Do3DSAndSubmit.

Transactions

For Transaction, J2/J5 validation-only operations return ResponseCode 700 or 701 which also count as success.

Documents

RecuringPayments

Note the path spelling: RecuringPayments (single r), as it appears in the official V11 schema.

There is no GetNewMuhlafim, UpdateMuhlafimDone, or SuspendedDealActivateOne endpoint in the V11 schema; do not invoke those.

Financial

CompanyOperations

Common Parameters

Alternative Payment Methods on Low Profile

Bit and PayPal have explicit URL fields you can render separately. Apple Pay and Google Pay are rendered inside the hosted Low Profile page itself once enabled on the terminal, so the API response does not expose dedicated URL fields for them.

API Version

V11 is the current API as of 2026. There is no public V12. Legacy .aspx interfaces with integer document codes (e.g. 101, 400) and the DealResponse shape predate V11; do not use them in new integrations.

API Docs

Official documentation: https://secure.cardcom.solutions/Api/v11/Docs Support center: https://support.cardcom.solutions

Cardcom V11 Response Pattern

ResponseCode + Description

Every Cardcom V11 API response is a JSON object that carries two top-level fields:

• `ResponseCode` (integer) -- 0 means success. Any non-zero value is a

developer or transaction error.

• `Description` (string) -- a human-readable explanation of the ResponseCode.

There is no DealResponse, TokenResponse, or InvoiceResponseCode field in V11. Those belong to the legacy .aspx interfaces. In V11, always check ResponseCode and read Description for the reason.

For Transactions/Transaction, J2/J5 validation-only operations return ResponseCode 700 or 701, which also count as success.

Per-operation response objects

In LowProfileResult, the nested objects (TranzactionInfo, TokenInfo, DocumentInfo, SuspendedInfo) are null when not applicable to the operation that ran. For example, TokenInfo is populated only for ChargeAndCreateToken and CreateTokenOnly operations.

Error codes

Cardcom V11 uses a single numeric ResponseCode space. The full numeric error reference (developer errors, card-decline reasons, document errors) is maintained in the official Cardcom documentation; do not hardcode a code-to-message table. Instead, branch on ResponseCode == 0 for success and surface the Description string for everything else.

See the official Cardcom error reference at https://secure.cardcom.solutions/Api/v11/Docs and the support center at https://support.cardcom.solutions.

Handling Pattern

import requests

resp = requests.post(
    "https://secure.cardcom.solutions/api/v11/Transactions/Transaction",
    json=payload,
    timeout=30,
).json()

if resp.get("ResponseCode") == 0:
    # Success: extract TranzactionId, Token, DocumentNumber, DocumentUrl
    transaction_id = resp["TranzactionId"]
else:
    # Failure: Description carries the exact reason
    log_error(
        f"Cardcom error {resp.get('ResponseCode')}: {resp.get('Description')}"
    )
    show_error("Payment could not be completed. Please try again.")

Notes

• Always check both the HTTP status (200 = request received) AND ResponseCode

(0 = operation succeeded). A 200 with a non-zero ResponseCode means the request was valid but the operation failed.

• Log the full response body, including Description, for any non-zero

ResponseCode to aid debugging.

• For LowProfileResult, also inspect the nested object ResponseCode values

(for example DocumentInfo.ResponseCode) when a document was requested.

Cardcom V11 Israeli Tax Document Types

All field names and enum values below are taken from the official Cardcom V11 OpenAPI specification at https://secure.cardcom.solutions/Api/v11/Docs (the Document, DocumentBase, DocumentToCreate, and Products schemas).

DocumentTypeToCreate (string enum)

The document type is set with the DocumentTypeToCreate string field on the Document object. It is a STRING enum, NOT an integer code. The full DocumentToCreate enum from the V11 schema:

If you need a value not listed, verify it against the official docs rather than guessing.

When to Use Each Type (Israeli Tax Law)

• `TaxInvoice`: Required when supplying goods/services to a business. The

buyer needs it to claim an input-VAT deduction. Issue at the time of supply or payment, whichever is earlier.

• `Receipt`: Confirms payment was received. Does NOT replace a tax invoice.
• `TaxInvoiceAndReceipt`: Combined document for when payment and supply

happen simultaneously. Standard for most B2C retail and e-commerce.

• *`Refund` types:** Required when reversing a previous document (refunds,

price reductions, returned goods).

• Osek Patur (exempt dealer): issues a Receipt only, not tax invoices.

Document Object Fields (DocumentBase + Document)

In the LowProfile/Create flow the document object is a DocumentLP; in the Transaction flow it is a DocumentTran (which uses DocumentDateDDMMYYYY and Languge). Both extend the same DocumentBase shown above.

Products Array Fields

VAT Handling

• The current Israeli VAT rate is 18% (effective January 2025).
• Set IsVatFree: true on a single product line for a VAT-exempt line item.
• Set IsVatFree: true on the Document object for a fully VAT-free document.
• Mixed documents: set IsVatFree per line item.
• Osek Patur (exempt dealer): should issue Receipt documents only.

Example: Tax Invoice + Receipt

{
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "Document": {
    "DocumentTypeToCreate": "TaxInvoiceAndReceipt",
    "Name": "Israel Israeli",
    "Email": "customer@example.com",
    "IsSendByEmail": true,
    "Languge": "he",
    "ISOCoinID": 1,
    "Products": [
      { "Description": "Annual software license", "UnitCost": 1180.00, "Quantity": 1 },
      { "Description": "Setup fee", "UnitCost": 236.00, "Quantity": 1 }
    ]
  }
}

Cardcom computes the VAT server-side from the line totals.

שער תשלומים קארדקום

סקירה

קארדקום היא חברת סליקה ישראלית עם יתרון ייחודי אחד: הפקת חשבוניות וקבלות משולבת בתשלום, לפי חוק המס הישראלי. שערי תשלום אחרים מטפלים רק בתשלום עצמו, אבל קארדקום יכולה להפיק אוטומטית חשבוניות מס וקבלות כחלק מתהליך התשלום, דבר שעסקים ישראליים חייבים לספק לפי חוק.

המדריך הזה עובר אתכם דרך אינטגרציה עם REST API V11 של קארדקום לתשלומים, טוקניזציה, חיובים חוזרים והפקת מסמכים. כל endpoint וכל שם שדה במדריך הזה לקוחים ממפרט ה-OpenAPI הרשמי של קארדקום V11.

תיעוד רשמי נמצא בכתובת https://secure.cardcom.solutions/Api/v11/Docs, מרכז התמיכה בכתובת https://support.cardcom.solutions. V11 הוא ה-API הנוכחי נכון ל-2026, אין V12 פומבי.

קארדקום בנוף הישראלי: מתחרה בטרנזילה, ישראפיי וביט עסקי. תמחור 2026 הוא בערך 1.2%-1.4% לעסקה עם תוכניות חודשיות שמתחילות בסביבות 59 ש"ח לחודש לתוסף החשבוניות. המספרים המדויקים נסגרים מול כל בית עסק. היתרון הייחודי שנשאר לעסקים ישראליים הוא הפקת מסמכי מס מובנית. לאינטגרציה עם טרנזילה, השתמשו ב-tranzila-payment-gateway במקום.

הוראות

שלב 1: בחירת דפוס אינטגרציה

רוב בתי העסק הישראליים משתמשים ב-Low Profile לתשלום הראשון ויצירת טוקן, ואז ב-endpoint של Transaction עם הטוקן השמור לחיובים חוזרים. כל זרימות התשלום יכולות להפיק חשבוניות אוטומטית על ידי צירוף אובייקט Document.

שלב 2: הגדרת אימות

פרטי הגישה ל-Cardcom API V11:

• TerminalNumber (מספר שלם), מזהה המסוף שלכם (תשתמשו ב-1000 לבדיקות)
• ApiName (מחרוזת), שם משתמש API
• ApiPassword (מחרוזת), סיסמת API, נדרשת רק להחזרים ולהפקת מסמכים, לא נשלחת בחיוב רגיל

סביבת בדיקות: מסוף 1000 עם ה-ApiName של ה-demo מאפשר בדיקת API בלי חיובים אמיתיים. כרטיס בדיקה: 4580000000000000, כל תפוגה עתידית, CVV 123.

תשמרו פרטי גישה בצורה מאובטחת, אף פעם לא בקוד מקור או ב-JavaScript בצד הלקוח.

שלב 3: מימוש זרימת התשלום

אינטגרציית Low Profile (מומלץ)

זה תהליך בשני שלבים.

שלב 3א: יצירת דף התשלום

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",
  "ISOCoinId": 1,
  "Language": "he",
  "Document": {
    "DocumentTypeToCreate": "TaxInvoiceAndReceipt",
    "Name": "שם הלקוח",
    "Email": "customer@example.com",
    "Products": [
      { "Description": "שם המוצר", "UnitCost": 100.00, "Quantity": 1 }
    ]
  }
}

התגובה היא CreateLowProfileResponse: תבדקו ResponseCode == 0 (הצלחה), תקראו את Description בכשלון. בהצלחה היא מחזירה LowProfileId (תשמרו אותו) ו-Url (תפנו לשם את הלקוח או תטמיעו כ-iframe). UrlToBit ו-UrlToPayPal מוחזרים גם הם כשהאמצעים האלה מופעלים במסוף שלכם.

השדה Operation שולט בהתנהגות: ChargeOnly (ברירת מחדל), ChargeAndCreateToken, CreateTokenOnly, SuspendedDeal, Do3DSAndSubmit.

שלב 3ב: קבלת התוצאות

אחרי שהתשלום מסתיים, קארדקום קוראת ל-WebHookUrl שלכם, או שאתם עושים שאילתה:

POST https://secure.cardcom.solutions/api/v11/LowProfile/GetLpResult
{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "LowProfileId": "id-from-step-3a"
}

התגובה היא LowProfileResult: תבדקו ResponseCode == 0. בהצלחה היא נושאת את TranzactionInfo (פרטי העסקה), TokenInfo (ה-Token השמור יחד עם CardMonth/CardYear), DocumentInfo (המסמך שהופק), ו-SuspendedInfo (לעסקאות מושהות). כל אובייקט מקונן הוא null כשהוא לא רלוונטי.

אמצעי תשלום חלופיים

תגובת ה-Low Profile כוללת כתובות לאמצעי תשלום חלופיים כשהם מופעלים במסוף שלכם:

UrlToBit ו-UrlToPayPal הם שדות URL מפורשים שאפשר להציג ליד טופס הכרטיס. Apple Pay ו-Google Pay עולים ככפתורי ארנק בתוך דף ה-Low Profile עצמו אחרי שמפעילים אותם במסוף, אז אין שדה URL נפרד בתגובה. הפעילו כל אמצעי במסוף שלכם בלוח הבקרה של קארדקום לפני שאתם סומכים עליו בפרודקשן.

שלב 4: הפקת מסמכי מס ישראליים

היתרון הייחודי של קארדקום הוא הפקת מסמכים אוטומטית עם התשלומים. זה קריטי לעסקים ישראליים כי חוק המס מחייב להנפיק מסמכים מתאימים לכל עסקה.

סוג המסמך נקבע באמצעות השדה `DocumentTypeToCreate`, שהוא enum מסוג מחרוזת (לא מספר שלם). ערכים נפוצים:

ה-enum המלא (DocumentToCreate במפרט ה-OpenAPI) כולל גם Quote, Order, OrderConfirmation, DeliveryNote, DemandForPayment, ProformaDealInvoice, ReceiptForTaxInvoice, CouponDocumentAndReceipt והגרסאות *Refund שלהם. תאמתו את הערך המדויק שאתם צריכים מול התיעוד הרשמי בכתובת https://secure.cardcom.solutions/Api/v11/Docs.

איך לכלול מסמך בתהליך תשלום: תוסיפו את אובייקט Document לבקשת LowProfile/Create או Transaction. קארדקום מפיקה את המסמך אוטומטית כשהתשלום מצליח.

הפקת מסמך עצמאית:

POST https://secure.cardcom.solutions/api/v11/Documents/CreateDocument
{
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "Document": {
    "DocumentTypeToCreate": "TaxInvoice",
    "Name": "שם הלקוח בעמ",
    "TaxId": "123456789",
    "Email": "customer@example.com",
    "IsSendByEmail": true,
    "Languge": "he",
    "ISOCoinID": 1,
    "Products": [
      { "Description": "שירותי פיתוח אתרים", "UnitCost": 5000.00, "Quantity": 1 }
    ]
  }
}

התגובה היא DocumentInfo: תבדקו ResponseCode == 0, ואז תקראו את DocumentType, DocumentNumber, AccountId ו-DocumentUrl (קישור ל-PDF).

שימו לב לאיות האמיתי של השדות ב-V11 בתוך אובייקט Document: DocumentTypeToCreate (enum מחרוזת), Name (ה"document To", נדרש, עד 50 תווים), TaxId (מספר עוסק או מספר זהות, מחליף את VAT_Number הישן), IsSendByEmail (מחליף את SendByEmail), Languge (האיות הרשמי של V11, חסרה ה-a השנייה), ISOCoinID (מחליף את CoinID), IsVatFree, ו-Products[] עם Description, UnitCost, Quantity, IsVatFree. ראו את references/document-types.md לרשימת השדות המלאה.

שלב 5: תשלומים חוזרים מבוססי טוקן

למנויים וחיובים חוזרים (הוראות קבע), קארדקום תומכת בשתי גישות:

• הוראת קבע על כרטיס אשראי, חיוב של Token שמור על מחזור קבוע. מטופל בשלב הזה.
• הוראת קבע בנקאית דרך מס"ב, חיוב ישיר מחשבון הבנק הישראלי של הלקוח. מנוהל דרך ה-endpoints של RecuringPayments (RecuringPayments/GetRecurringPayment, GetRecurringPaymentHistory, IsBankNumberValid). תשתמשו בזה כשהלקוח מעדיף חיוב בנקאי על פני חיוב כרטיס או כשאין כרטיס זמין. ההוראה עצמה מוקמת מלוח הבקרה של קארדקום.

לתשלום חוזר מבוסס כרטיס:

1. יצירת טוקן בתשלום הראשון. תשתמשו ב-Low Profile עם Operation: "ChargeAndCreateToken" (או "CreateTokenOnly"). ה-LowProfileResult מחזיר TokenInfo עם Token, CardMonth, CardYear ו-TokenExDate (התאריך שבו הטוקן נמחק ממערכת קארדקום).

2. אחסון הטוקן בצורה מאובטחת. תשמרו את מחרוזת ה-Token, תפוגת הכרטיס ו-4 הספרות האחרונות. הטוקן קשור למסוף שלכם.

3. חיוב הטוקן דרך endpoint של Transaction:

POST https://secure.cardcom.solutions/api/v11/Transactions/Transaction
{
  "TerminalNumber": 1000,
  "ApiName": "your-api-name",
  "Token": "token-uuid",
  "CardExpirationMMYY": "1227",
  "Amount": 99.00,
  "ISOCoinId": 1,
  "Document": {
    "DocumentTypeToCreate": "TaxInvoiceAndReceipt",
    "Name": "שם המנוי",
    "Email": "customer@example.com",
    "IsSendByEmail": true,
    "Products": [
      { "Description": "מנוי חודשי", "UnitCost": 99.00, "Quantity": 1 }
    ]
  }
}

התגובה היא TransactionInfo: תבדקו ResponseCode == 0 (שימו לב ש-700 ו-701 נחשבים גם הם הצלחה לעסקאות אימות בלבד מסוג J2/J5), ואז תקראו את TranzactionId, Token, DocumentNumber ו-DocumentUrl. כל חיוב טוקן יכול להפיק ולשלוח חשבונית במייל אוטומטית כשמצורף אובייקט Document.

שלב 6: ביצוע החזרים

החזר עסקה לפי מזהה העסקה של קארדקום:

POST https://secure.cardcom.solutions/api/v11/Transactions/RefundByTransactionId
{
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "TransactionId": 219282004,
  "PartialSum": 100.00,
  "CancelOnly": false,
  "AllowMultipleRefunds": false
}

ApiPassword נדרשת להחזרים. PartialSum מחזיר חלק מהעסקה (תשמיטו אותו כדי להחזיר את הסכום המלא). CancelOnly: true מבטל עסקה לפני שהיא הופקדה. התגובה היא RefundByTransactionIdResp: תבדקו ResponseCode == 0, ואז תקראו את NewTranzactionId (מזהה עסקת ההחזר).

כדי להנפיק את מסמך הזיכוי התואם, תקראו ל-Documents/CreateDocument עם DocumentTypeToCreate של זיכוי כמו TaxInvoiceAndReceiptRefund או TaxInvoiceRefund.

שלב 7: עסקאות מושהות

עסקה מושהית מאשרת כוונת תשלום בלי חיוב מיידי:

1. תיצרו סשן Low Profile עם Operation: "SuspendedDeal". 2. ה-LowProfileResult מחזיר SuspendedInfo עם SuspendedDealId. 3. תחייבו את העסקה המושהית מאוחר יותר דרך לוח הבקרה של קארדקום או דרך Transaction API.

שימושי להרשאות מראש ולשירותים שמחויבים אחרי אספקה. קריאת החיוב המאוחר המדויקת מתוארת בתיעוד הרשמי.

שלב 8: טיפול בשגיאות

כל endpoint ב-V11 מחזיר מספר שלם ResponseCode ומחרוזת Description. ResponseCode == 0 משמעו הצלחה, כל ערך שאינו אפס הוא שגיאת מפתח/עסקה ו-Description נושא את הסיבה הקריאה לאדם.

import requests

resp = requests.post(
    "https://secure.cardcom.solutions/api/v11/Transactions/Transaction",
    json=payload,
).json()

if resp.get("ResponseCode") == 0:
    deal_id = resp["TranzactionId"]
else:
    log_error(f"Cardcom error {resp.get('ResponseCode')}: {resp.get('Description')}")

תמיד תבדקו גם את סטטוס ה-HTTP (200 משמעו שהבקשה התקבלה) וגם את ResponseCode (0 משמעו שהפעולה הצליחה). התיעוד הרשמי בכתובת https://secure.cardcom.solutions/Api/v11/Docs נושא את מדריך השגיאות המספרי המלא, אל תקודדו מיפוי קבוע של קוד שגיאה להודעה, תקראו את Description במקום. ראו את references/api-responses.md לדפוס הטיפול.

דוגמאות

דוגמה 1: checkout לחנות מקוונת עם חשבונית

המשתמש אומר: "אני צריך לקבל תשלומים באתר המסחר האלקטרוני הישראלי שלי ולהפיק חשבוניות מס אוטומטית" פעולות: 1. תבחרו Low Profile עם DocumentTypeToCreate: "TaxInvoiceAndReceipt". 2. תיצרו את דף ה-Low Profile דרך LowProfile/Create עם פרטי המוצרים באובייקט Document. 3. תממשו handler ל-WebHookUrl שקורא ל-LowProfile/GetLpResult. תוצאה: הלקוח משלם ומקבל אוטומטית חשבונית מס/קבלה במייל כ-PDF.

דוגמה 2: מנוי SaaS חודשי

המשתמש אומר: "אני מפעיל מוצר SaaS, אני צריך לחייב משתמשים 149 שח בחודש ולשלוח להם חשבוניות" פעולות: 1. תשלום ראשון: LowProfile/Create עם Operation: "ChargeAndCreateToken". 2. תשמרו את ה-Token, CardMonth, CardYear מתוך TokenInfo. 3. cron חודשי: Transactions/Transaction עם הטוקן ואובייקט Document לכל מחזור חיוב. תוצאה: חיוב חוזר אוטומטי עם הפקת חשבונית חודשית.

דוגמה 3: חשבונית עצמאית בלי תשלום

המשתמש אומר: "אני צריך להפיק חשבונית מס על העברה בנקאית שכבר קיבלתי" פעולות: 1. תשתמשו ב-Documents/CreateDocument (בלי עיבוד תשלום). 2. תגדירו DocumentTypeToCreate: "TaxInvoice". 3. תכללו Name, TaxId, Products[], תגדירו IsSendByEmail: true עם מייל הלקוח. תוצאה: חשבונית מס מופקת ונשלחת במייל בלי לעבד כרטיס אשראי.

דוגמה 4: ביצוע החזר עם מסמך זיכוי

המשתמש אומר: "לקוח רוצה החזר על הזמנה מספר 5678, צריך גם להנפיק חשבונית זיכוי" פעולות: 1. תקראו ל-Transactions/RefundByTransactionId עם TransactionId ו-ApiPassword. 2. תבדקו ResponseCode == 0 ותקראו את NewTranzactionId. 3. תקראו ל-Documents/CreateDocument עם DocumentTypeToCreate: "TaxInvoiceAndReceiptRefund". תוצאה: ההחזר מעובד ומסמך הזיכוי התואם מופק.

דוגמה 5: קבלת תשלום Bit, Apple Pay ו-Google Pay

המשתמש אומר: "אני רוצה לאפשר ללקוחות לשלם גם עם Bit, Apple Pay ו-Google Pay בנוסף לכרטיס אשראי" פעולות: 1. תפעילו כל אמצעי (Bit, Apple Pay, Google Pay) במסוף קארדקום דרך לוח הבקרה. 2. תיצרו סשן Low Profile כרגיל דרך LowProfile/Create. 3. תציגו את UrlToBit מהתגובה לצד טופס הכרטיס. Apple Pay ו-Google Pay יופיעו ככפתורי ארנק בתוך דף ה-Low Profile עצמו, בלי URL נפרד. תוצאה: לקוחות יכולים לבחור בין כרטיס אשראי, Bit, Apple Pay ו-Google Pay, אותו תהליך webhook.

ספריות קהילתיות

• @tsdiapi/cardcom (TypeScript/Node.js), לקוח API V11 עם תשלומים, החזרים, טוקניזציה, שאילתות עסקאות. התקנה: npm install @tsdiapi/cardcom
• CardCom/OpenFields-FrontEnd-React (React), דוגמת OpenFields רשמית. ראו https://github.com/CardCom/OpenFields-FrontEnd-React
• CardCom/OpenFields-Backend-Node (Node.js), דוגמת backend רשמית. ראו https://github.com/CardCom/OpenFields-Backend-Node

קישורים לחומרי עזר

משאבים מצורפים

חומרי עזר

• references/api-endpoints.md, מדריך endpoints של Cardcom REST API V11: נתיבי LowProfile, Transactions, Documents, RecuringPayments, Financial ו-CompanyOperations עם שדות הבקשה/תגובה המרכזיים שלהם. תסתכלו עליו כשאתם בונים אינטגרציות API.
• references/api-responses.md, דפוס התגובה ResponseCode + Description של V11, אובייקטי התגובה לכל פעולה, וזרימת הטיפול המומלצת בשגיאות. תסתכלו עליו כשאתם מדבגים קריאות API שנכשלו.
• references/document-types.md, ה-enum המחרוזתי DocumentTypeToCreate, רשימת השדות של אובייקט Document, וטיפול במעמ לפי חוק המס הישראלי. תסתכלו עליו כשאתם מחליטים איזה סוג מסמך להפיק.

סקריפטים

• scripts/validate_cardcom_response.py, מאמת תגובת API של קארדקום V11: בודק ResponseCode, מציג את Description, ומוודא שדות צפויים לפעולות עסקה, טוקן ומסמך. להרצה: python scripts/validate_cardcom_response.py --help

מלכודות נפוצות

• בדיקת ההצלחה ב-V11 היא ResponseCode == 0, לא DealResponse == 0. DealResponse לא קיים ב-V11, סוכנים שאומנו על דוגמאות קארדקום ישנות ממציאים אותו. כל endpoint ב-V11 מחזיר ResponseCode יחד עם מחרוזת Description.
• DocumentTypeToCreate הוא enum מסוג מחרוזת ("TaxInvoiceAndReceipt", "TaxInvoice", "Receipt", ...), לא קוד מספרי. קודי מסמך מספריים כמו 101 או 400 שייכים לממשקי .aspx ישנים, לא ל-V11.
• ה-TerminalNumber חייב להישלח כמספר שלם, לא כמחרוזת. סוכנים נוטים לעטוף אותו במירכאות.
• ApiPassword נדרשת ל-RefundByTransactionId ול-CreateDocument, אבל לא נשלחת בחיוב רגיל של LowProfile/Create או Transaction.
• שימו לב לאיות האמיתי של השדות ב-V11: Languge (חסרה ה-a השנייה) בתוך אובייקט Document, ISOCoinID / ISOCoinId, IsSendByEmail (לא SendByEmail), TaxId (לא VAT_Number).
• שיעור המעמ הנוכחי בישראל הוא 18% (מינואר 2025; ההצעה התקציבית של ינואר 2026 להעלות ל-19% נדחתה). קארדקום מחשבת מעמ בצד השרת, אז סכומי המסמך מטופלים לפי דגל IsVatFree.
• היקף PCI: Low Profile מארח שומר אתכם ב-SAQ-A. שרת-לשרת Transaction עם CardNumber/CVV2 גולמיים נופל ל-SAQ-D. PCI DSS v4.0 הפך לחובה במרץ 2025, אז עדיף להישאר עם Low Profile או טוקנים אלא אם יש סיבה אמיתית לגעת בנתוני כרטיס גולמיים.
• לוח הסליקה הכספית נקבע ברמת המסוף, לא בכל בקשה. סליקה שבועית מפקידה ביום רביעי שאחרי העסקה. סליקה חודשית מפקידה ב-6 לחודש שאחרי. אל תנסו להגדיר את זה דרך ה-API.
• ל-Apple Pay ו-Google Pay אין שדות URL נפרדים כמו UrlToBit / UrlToPayPal. הם מופיעים ככפתורי ארנק בתוך דף ה-Low Profile עצמו אחרי שמפעילים אותם במסוף בלוח הבקרה.

פתרון בעיות

שגיאה: ResponseCode שאינו אפס ב-LowProfile/Create

סיבה: בעיית אימות או ולידציה בבקשה. פתרון: תקראו את מחרוזת ה-Description בתגובה, היא מציינת את הבעיה המדויקת. תוודאו ש-TerminalNumber הוא מספר שלם ו-ApiName נכון. מדריך השגיאות המספרי המלא נמצא בכתובת https://secure.cardcom.solutions/Api/v11/Docs.

שגיאה: "דף Low Profile נטען אבל התשלום נכשל"

סיבה: בדרך כלל בעיה ב-WebHookUrl או בכתובות ה-redirect. פתרון: תוודאו ש-SuccessRedirectUrl, FailedRedirectUrl ו-WebHookUrl הן כתובות HTTPS נגישות מהאינטרנט. כתובות localhost לא עובדות, תשתמשו ב-ngrok לפיתוח.

שגיאה: "החזר מחזיר ResponseCode שאינו אפס"

סיבה: ApiPassword חסרה, או שהעסקה כבר הופקדה ושלחתם CancelOnly: true. פתרון: תכללו ApiPassword בכל בקשת החזר. תשתמשו ב-CancelOnly: true רק לפני הפקדה, אחרי הפקדה תשלחו החזר אמיתי (תשמיטו את CancelOnly או תגדירו אותו false).

שגיאה: "חשבונית נוצרה אבל לא נשלחה במייל"

סיבה: IsSendByEmail לא מוגדר או שחסר אימייל. פתרון: תגדירו IsSendByEmail: true ותכללו Email תקין באובייקט Document. תבדקו בתיקיית ספאם, קארדקום שולחת מהדומיין שלה.

שגיאה: "חיוב טוקן מצליח אבל אין חשבונית"

סיבה: אובייקט Document חסר מבקשת ה-Transaction. פתרון: תכללו את אובייקט Document המלא עם DocumentTypeToCreate, Name ו-Products בכל חיוב טוקן. הפקת מסמכים היא opt-in לכל עסקה.