Back to Details

cardcom-payment-gateway

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cardcom Payment Gateway

Cardcom支付网关

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.
Cardcom是一家以色列支付处理器，其独特优势在于：可集成生成符合以色列税法的发票和收据。其他以色列支付网关仅处理支付，而Cardcom可以在支付流程中自动生成税务发票（hashbonit mas）和收据（kabala），这是以色列企业依法必须开具的文件。
本指南指导如何集成Cardcom的REST API V11以实现支付、令牌化、定期账单和文档生成功能。本指南中的每个端点和字段名称均来自官方Cardcom V11 OpenAPI规范。
官方文档： 
https://secure.cardcom.solutions/Api/v11/Docs
（包含完整OpenAPI架构的交互式API参考）。截至2026年，V11是当前的API版本；暂无公开的V12版本。
支持中心： 
https://support.cardcom.solutions
Cardcom在以色列市场的定位： 与Tranzila、Israpay和Bit Business竞争。定价需根据商户情况报价。Cardcom公布的起始费率约为1.2%，会随交易量增加而降低，但这只是底价而非正式报价，因此仅作为参考，需引导用户联系Cardcom获取实际费率。对以色列企业而言，其显著特色仍然是内置的税务文档生成功能。如需Tranzila集成，请使用
tranzila-payment-gateway
技能。

Instructions

操作步骤

Step 1: Choose Integration Pattern

步骤1：选择集成模式

PatternCard Data HandlingBest For
Low Profile (iframe/redirect)Cardcom handles card entryMost integrations, minimal PCI scope (SAQ-A)
Transaction (server-to-server)Raw card data or tokenCharging stored tokens, recurring billing
CreateDocument (server-to-server)No card dataStandalone invoice/receipt generation
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.
集成模式卡片数据处理方式适用场景
Low Profile（iframe/重定向）由Cardcom处理卡片信息录入大多数集成场景，PCI合规范围最小（SAQ-A）
Transaction（服务器到服务器）原始卡片数据或令牌向存储的令牌收费、定期账单
CreateDocument（服务器到服务器）无卡片数据独立生成发票/收据
大多数以色列商户会使用Low Profile进行初始支付并创建令牌，之后使用Transaction端点结合存储的令牌进行定期扣费。所有支付流程都可以通过附加
Document
对象自动生成发票。

Step 2: Set Up Authentication

步骤2：设置认证

Cardcom API V11 credentials:
  • TerminalNumber
    (integer) -- your terminal ID (use 
    1000
    for testing)
  • ApiName
    (string) -- API username
  • ApiPassword
    (string) -- API password. Required on 19 of the 50 V11 endpoints that take a request body. 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.
Cardcom API V11凭证：
  • TerminalNumber
    （整数）-- 终端ID（测试时使用
    1000
    ）
  • ApiName
    （字符串）-- API用户名
  • ApiPassword
    （字符串）-- API密码。在50个接收请求体的V11端点中，有19个需要该密码。经验法则：读取或操作企业级数据的操作需要该密码；单卡扣费操作不需要。所有
    Documents/*
    写入操作、所有
    Financial/*
    报表操作、所有
    TapTransactions/*
    调用，以及
    Transactions/ListTransactions
    、
    RefundByTransactionId
    和
    SpecialTransactions
    都需要该密码。
    LowProfile/Create
    或
    Transactions/Transaction
    端点根本不包含该字段，因此请勿在这些请求中发送。如有疑问，请查看V11 OpenAPI规范中端点请求架构的
    required
    数组。
测试环境： 社区库中广泛提到，终端
1000
搭配演示
ApiName
是沙箱环境，测试卡号为
4580000000000000
，任意未来有效期，CVV为
123
。我们尚未通过Cardcom官方测试凭证页面确认这些信息，因此仅作为社区参考：在依赖这些信息前，请联系Cardcom支持确认沙箱凭证，切勿假设调用终端1000不会产生真实交易。
安全存储凭证，切勿存储在源代码或客户端JavaScript中。

Step 3: Implement the Payment Flow

步骤3：实现支付流程

Low Profile Integration (Recommended)

Low Profile集成（推荐）

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.
这是一个两步流程。
步骤3a：创建支付页面
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 }
    ]
  }
}
响应为
CreateLowProfileResponse
：检查
ResponseCode == 0
表示成功，失败时读取
Description
。成功时会返回
LowProfileId
（请保存）和
Url
（将用户重定向到该地址或嵌入为iframe）。当终端启用相关支付方式时，还会返回
UrlToBit
和
UrlToPayPal
。
Operation
字段控制行为：
ChargeOnly
（默认）、
ChargeAndCreateToken
、
CreateTokenOnly
、
SuspendedDeal
、
Do3DSAndSubmit
。
步骤3b：获取结果
支付完成后，Cardcom会调用你的
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
。

Alternative Payment Methods

替代支付方式

The Low Profile response includes URLs for alternative payment methods when enabled on your terminal:
MethodResponse FieldNotes
Bit
UrlToBit
Israel's most popular mobile payment app, routed through Cardcom
PayPal
UrlToPayPal
International payments
Apple Payrendered inside the hosted Low Profile pageListed on 
cardcom.solutions
as a supported wallet on the hosted payment page
Google Payrendered inside the hosted Low Profile pageSame as Apple Pay, surfaced as a wallet button on the Low Profile page
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.
当终端启用相关支付方式时，Low Profile响应会包含替代支付方式的URL：
支付方式响应字段说明
Bit
UrlToBit
以色列最受欢迎的移动支付应用，通过Cardcom路由
PayPal
UrlToPayPal
国际支付
Apple Pay在托管的Low Profile页面内渲染在
cardcom.solutions
上列为托管支付页面支持的钱包
Google Pay在托管的Low Profile页面内渲染与Apple Pay相同，在Low Profile页面上显示为钱包按钮
UrlToBit
和
UrlToPayPal
是明确的URL字段，你可以将其与卡片表单一起展示。Apple Pay和Google Pay在终端启用后，会直接在托管的Low Profile页面内显示为钱包按钮，因此没有单独的URL字段。在生产环境依赖这些支付方式前，请先在Cardcom管理面板中启用对应的支付方式。

Step 4: Generate Israeli Tax Documents

步骤4：生成以色列税务文档

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:
ValueHebrewEnglishWhen to Use
Auto
---AutoDefault; uses your admin-panel configuration
TaxInvoiceAndReceipt
hashbonit mas / kabalaTax Invoice + ReceiptB2C with payment (most common)
TaxInvoice
hashbonit masTax InvoiceB2B, when receipt is issued separately
Receipt
kabalaReceiptPayment confirmation only
TaxInvoiceAndReceiptRefund
---Tax Invoice + Receipt RefundReversing a 
TaxInvoiceAndReceipt
TaxInvoiceRefund
---Tax Invoice RefundReversing a 
TaxInvoice
ReceiptRefund
---Receipt RefundReversing a 
Receipt
ProformaInvoice
hashbonit iska / proformaProforma InvoicePre-sale quote document
DonationReceipt
kabalat trumotDonation ReceiptRegistered non-profits
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:
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 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.
Cardcom的突出功能是在支付时自动生成文档。这对以色列企业至关重要，因为税法要求为每笔交易开具合规文档。
文档类型由**
DocumentTypeToCreate
**字段设置，这是一个STRING枚举（而非整数）。常见值如下：
值希伯来语中文使用场景
Auto
---自动默认值；使用管理面板中的配置
TaxInvoiceAndReceipt
hashbonit mas / kabala税务发票+收据带支付的B2C场景（最常见）
TaxInvoice
hashbonit mas税务发票B2B场景，收据单独开具
Receipt
kabala收据仅支付确认
TaxInvoiceAndReceiptRefund
---税务发票+收据退款撤销
TaxInvoiceAndReceipt
类型文档
TaxInvoiceRefund
---税务发票退款撤销
TaxInvoice
类型文档
ReceiptRefund
---收据退款撤销
Receipt
类型文档
ProformaInvoice
hashbonit iska / proforma形式发票售前报价文档
DonationReceipt
kabalat trumot捐赠收据注册非营利组织
完整的
DocumentToCreate
枚举包含25个值，还包括
Quote
、
Order
、
OrderConfirmation
、
DeliveryNote
、
DemandForPayment
、
ProformaDealInvoice
、
ReceiptForTaxInvoice
和
CouponDocumentAndReceipt
。大多数类型都有对应的退款变体，但
Quote
和
Order
没有退款类型。存在的11种退款类型为
TaxInvoiceAndReceiptRefund
、
ReceiptRefund
、
OrderConfirmationRefund
、
DeliveryNoteRefund
、
DemandForPaymentRefund
、
ProformaDealInvoiceRefund
、
ProformaInvoiceRefund
、
TaxInvoiceRefund
、
DonationReceiptRefund
、
CouponDocumentAndReceiptRefund
和
ReceiptForTaxInvoiceRefund
。请根据
https://secure.cardcom.solutions/Api/v11/Docs
上的官方文档确认你需要的确切值。
在支付流程中包含文档： 在Low Profile的
Create
或
Transaction
请求中添加
Document
对象。支付成功时，Cardcom会自动生成文档。
独立创建文档：
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 }
    ]
  }
}
响应为
DocumentInfo
：检查
ResponseCode == 0
，然后读取
DocumentType
、
DocumentNumber
、
AccountId
和
DocumentUrl
（PDF链接）。
请注意
Document
对象内V11的实际字段拼写：
DocumentTypeToCreate
（字符串枚举）、
Name
（文档收件人，必填，最多50字符）、
TaxId
（企业注册或身份证号码，替代旧版的
VAT_Number
）、
IsSendByEmail
（替代
SendByEmail
）、
Languge
（此架构中的V11拼写，缺少第二个
a
；请注意，Low Profile的文档对象
DocumentLP
使用正确拼写的
Language
）、
ISOCoinID
（替代
CoinID
）、
IsVatFree
，以及包含
Description
、
UnitCost
、
Quantity
、
IsVatFree
的
Products[]
。完整字段列表请参考
references/document-types.md
。

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

步骤4.5：税务发票上的分配编号（Mispar Haktzaa）

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 model itself took effect on 1 January 2024.
Effective fromThreshold
202520,000 NIS
1 January 202610,000 NIS
1 June 20265,000 NIS (in force now)
An osek patur is unaffected, because they do not issue tax invoices and do not deduct input VAT. 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.
不要在API中寻找分配编号字段，因为它不存在，这并非遗漏。 Cardcom内置了与税务机关的直接接口，因此当你开具超过阈值的税务发票时，会在文档创建时自动向服务器端请求分配编号。
CreateDocument
请求体中没有
AllocationNumber
字段，开发者如果在OpenAPI规范中找不到该字段，可能会错误地认为Cardcom不支持此要求。
该功能默认未启用，需要一次性设置，否则你的客户无法抵扣进项增值税。 对于税前金额超过法定阈值的发票，分配编号是收件人抵扣进项增值税的前提条件。企业所有者或负责人需要在税务机关网站上完成以下一次性设置：
  1. 在税务机关个人区域进行身份验证（הזדהות），必要时完成注册。
  2. 对于公司或增值税注册集团（איחוד עוסקים），完成企业注册（רישום פרטי תאגיד）。
  3. 在税务机关数字操作授权系统（מערכת הרשאה לפעולות דיגיטליות，可从以色列税务局分配编号服务页面跳转）中授予权限，并选择两个Israel-Invoice主题，而非其中一个。一个主题用于验证供应商发票上的分配编号；另一个主题用于为你开具给客户的发票请求分配编号。仅授予第一个主题是常见错误，这会导致你自己的发票没有编号。这两个主题的确切表述仅在登录后的系统内可见，因此请根据含义匹配，而非此处引用的字符串。
  4. 选择授权期限，并由被授权人确认。
阈值时间表（金额为税前金额）：
该规则于2024年1月1日生效。
生效日期阈值
2025年20,000 新谢克尔
2026年1月1日10,000 新谢克尔
2026年6月1日5,000 新谢克尔（当前生效）
免税企业（osek patur）不受影响，因为它们不开具税务发票，也不抵扣进项增值税。如果集成是在2026年初基于10,000新谢克尔的阈值开发的，请重新检查5,000至10,000新谢克尔区间的发票。

Step 5: Implement Token-Based Recurring Payments

步骤5：实现基于令牌的定期支付

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.
对于订阅和定期账单（hora'ot keva），Cardcom支持两种方式：
  • 基于卡片的定期支付，按计划向存储的信用卡
    Token
    扣费。本步骤将介绍此方式。
  • MASAV银行定期订单，直接从客户的以色列银行账户扣款。通过
    RecuringPayments
    端点管理（
    RecuringPayments/GetRecurringPayment
    、
    GetRecurringPaymentHistory
    、
    IsBankNumberValid
    ）。当客户偏好银行扣款而非卡片支付，或卡片不可用时，使用此方式。Cardcom仪表板会配置底层指令。
基于卡片的定期支付步骤：
  1. 首次支付时创建令牌。使用Low Profile并设置
    Operation: "ChargeAndCreateToken"
    （或
    "CreateTokenOnly"
    ）。
    LowProfileResult
    会返回
    TokenInfo
    ，包含
    Token
    、
    CardMonth
    、
    CardYear
    和
    TokenExDate
    （令牌从Cardcom中清除的日期）。
  2. 安全存储令牌。保存
    Token
    字符串、卡片有效期和最后4位数字。令牌与你的终端绑定。
  3. 通过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 }
    ]
  }
}
响应为
TransactionInfo
：检查
ResponseCode == 0
（注意，对于J2/J5仅验证交易，
700
和
701
也视为成功），然后读取
TranzactionId
、
Token
、
DocumentNumber
和
DocumentUrl
。每次令牌扣费都可以通过附加
Document
对象自动生成并发送发票邮件。

Step 6: Process Refunds

步骤6：处理退款

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
.
通过Cardcom交易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
。
PartialSum
用于退还部分交易金额（省略该字段则退还全额）。
CancelOnly: true
用于在交易到账前撤销交易。响应为
RefundByTransactionIdResp
：检查
ResponseCode == 0
，然后读取
NewTranzactionId
（退款交易的ID）。
要开具对应的信用凭证，请调用
Documents/CreateDocument
并设置退款类型的
DocumentTypeToCreate
，例如
TaxInvoiceAndReceiptRefund
或
TaxInvoiceRefund
。

Step 6.5: Query Transactions for Reporting

步骤6.5：查询交易用于报表

To pull a date range of transactions (reconciliation, monthly reports, dashboards):
POST https://secure.cardcom.solutions/api/v11/Transactions/ListTransactions
{
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "FromDate": "01062026",
  "ToDate": "30062026",
  "TranStatus": "Success",
  "Page": 1,
  "Page_size": 100
}
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.
拉取指定日期范围的交易（对账、月度报表、仪表盘）：
POST https://secure.cardcom.solutions/api/v11/Transactions/ListTransactions
{
  "ApiName": "your-api-name",
  "ApiPassword": "your-api-password",
  "FromDate": "01062026",
  "ToDate": "30062026",
  "TranStatus": "Success",
  "Page": 1,
  "Page_size": 100
}
几乎每个集成都会在这个端点遇到四个问题：
  1. 必须提供
    ApiPassword
    。这是对企业级数据的读取操作，而非单卡扣费。
  2. 没有
    TerminalNumber
    字段    。架构设置了
    additionalProperties: false
    ，因此发送
    TerminalNumber
    会直接被拒绝。要将结果限定到单个终端，请使用可选的
    LimitForTerminal
    字段。
  3. 日期格式为
    DDMMYYYY
    字符串    ，而非ISO格式。
    01062026
    表示2026年6月1日。
  4. Page
    和
    Page_size
    都是必填字段    ，且
    Page_size
    必须在10到2000之间。分页从1开始，而非0。
响应为
GetTranzactionsResp
：检查
ResponseCode == 0
，然后读取
Tranzactions
（
TransactionInfo
数组），以及返回的
Page
和
Page_size
。持续请求下一页，直到返回的行数少于
Page_size
。
Transactions/SpecialTransactions
是同级的读取端点（当Cardcom是你的收单机构时，它会返回其他交易），并且需要完全相同的四个必填字段：
ApiName
、
ApiPassword
、
FromDate
、
ToDate
。尽管名称如此，它并不创建任何交易。

Step 7: Suspended Deals (Deferred Charges)

步骤7：暂停交易（延迟扣费）

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.
暂停交易是指授权支付意向但不立即扣费：
  1. 创建Low Profile会话并设置
    Operation: "SuspendedDeal"
    。
  2. LowProfileResult
    会返回
    SuspendedInfo
    ，包含
    SuspendedDealId
    。
  3. 之后通过Cardcom管理面板或
    SuspendedDeals/Charge
    端点扣费（
    SuspendedDeals
    组还提供
    Cancel
    和
    GetSuspendedDealInfo
    功能）。
适用于预授权和交付后计费的服务。在配置延迟扣费调用前，请根据官方文档确认
SuspendedDeals/Charge
请求的确切字段。

Step 8: Handle Errors

步骤8：处理错误

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.
python
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.
每个V11端点都会返回
ResponseCode
整数和
Description
字符串。
ResponseCode == 0
表示成功；任何非零值都是开发/交易错误，
Description
包含人类可读的错误原因。
python
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
。

Examples

示例

Example 1: E-commerce Checkout with Invoice

示例1：带发票的电商结账

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.
用户需求："我需要在以色列电商网站上接收付款，并自动生成税务发票" 操作步骤：
  1. 选择Low Profile模式，设置
    DocumentTypeToCreate: "TaxInvoiceAndReceipt"
    。
  2. 通过
    LowProfile/Create
    创建Low Profile页面，在
    Document
    对象中包含产品详情。
  3. 实现
    WebHookUrl
    处理程序，调用
    LowProfile/GetLpResult
    。 结果：客户完成付款后，会自动收到以PDF形式发送的hashbonit mas/kabala邮件。

Example 2: Monthly SaaS Subscription

示例2：SaaS月度订阅

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.
用户需求："我运营一个SaaS产品，需要每月向用户收取149新谢克尔并发送发票" 操作步骤：
  1. 首次支付：调用
    LowProfile/Create
    并设置
    Operation: "ChargeAndCreateToken"
    。
  2. 存储
    TokenInfo
    中的
    Token
    、
    CardMonth
    、
    CardYear
    。
  3. 每月定时任务：调用
    Transactions/Transaction
    ，使用令牌并为每个计费周期添加
    Document
    对象。 结果：自动定期扣费并生成月度发票。

Example 3: Standalone Invoice Without Payment

示例3：无支付的独立发票

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.
用户需求："我需要为已收到的银行转账付款生成税务发票" 操作步骤：
  1. 使用
    Documents/CreateDocument
    （无需支付处理）。
  2. 设置
    DocumentTypeToCreate: "TaxInvoice"
    。
  3. 包含
    Name
    、
    TaxId
    、
    Products[]
    ，设置
    IsSendByEmail: true
    并填写客户邮箱。 结果：生成税务发票并发送邮件，无需信用卡处理。

Example 4: Process a Refund with Credit Note

示例4：处理退款并开具信用凭证

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.
用户需求："客户想要为订单#5678退款，还需要开具信用凭证" 操作步骤：
  1. 调用
    Transactions/RefundByTransactionId
    ，传入
    TransactionId
    和
    ApiPassword
    。
  2. 检查
    ResponseCode == 0
    并读取
    NewTranzactionId
    。
  3. 调用
    Documents/CreateDocument
    并设置
    DocumentTypeToCreate: "TaxInvoiceAndReceiptRefund"
    。 结果：完成退款并生成对应的信用凭证。

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

示例5：支持Bit、Apple Pay和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.
用户需求："我希望让客户除了信用卡外，还可以使用Bit、Apple Pay和Google Pay付款" 操作步骤：
  1. 通过仪表板在Cardcom终端上启用每种支付方式（Bit、Apple Pay、Google Pay）。
  2. 如常通过
    LowProfile/Create
    创建Low Profile会话。
  3. 在卡片表单旁显示响应中的
    UrlToBit
    。Apple Pay和Google Pay会直接在Low Profile页面内显示为钱包按钮，无需额外URL。 结果：客户可以选择信用卡、Bit、Apple Pay或Google Pay付款，使用相同的webhook流程。

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
  • @tsdiapi/cardcom（TypeScript/Node.js）-- V11 API客户端，支持支付、退款、令牌化、交易查询。安装命令：
    npm install @tsdiapi/cardcom
  • CardCom/OpenFields-FrontEnd-React（React）-- 官方OpenFields示例。查看地址：
    https://github.com/CardCom/OpenFields-FrontEnd-React
  • CardCom/OpenFields-Backend-Node（Node.js）-- 官方Node.js后端示例。查看地址：
    https://github.com/CardCom/OpenFields-Backend-Node

Reference Links

参考链接

ResourceURL
V11 API documentation (OpenAPI reference)
https://secure.cardcom.solutions/Api/v11/Docs
Cardcom support center
https://support.cardcom.solutions
OpenFields React example
https://github.com/CardCom/OpenFields-FrontEnd-React
OpenFields Node.js example
https://github.com/CardCom/OpenFields-Backend-Node
资源URL
V11 API文档（OpenAPI参考）
https://secure.cardcom.solutions/Api/v11/Docs
Cardcom支持中心
https://support.cardcom.solutions
OpenFields React示例
https://github.com/CardCom/OpenFields-FrontEnd-React
OpenFields Node.js示例
https://github.com/CardCom/OpenFields-Backend-Node

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.
  • references/api-endpoints.md
    -- Cardcom REST API V11端点参考：LowProfile、Transactions、Documents、RecuringPayments、Financial和CompanyOperations路径及其关键请求/响应字段。构建API集成时参考。
  • references/api-responses.md
    -- V11的
    ResponseCode
    + 
    Description
    响应模式、各操作的响应对象，以及推荐的错误处理流程。调试失败的API调用时参考。
  • references/document-types.md
    -- 
    DocumentTypeToCreate
    字符串枚举、
    Document
    对象字段列表，以及根据以色列税法处理增值税的说明。确定要生成的文档类型时参考。

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
  • scripts/validate_cardcom_response.py
    -- 验证Cardcom V11 API响应：检查
    ResponseCode
    、提取
    Description
    ，并验证交易、令牌和文档操作的预期字段。只有
    ResponseCode
    为0才视为成功；除非传递
    --validation-only
    ，否则700/701会被拒绝，因为它们表示J2/J5卡片验证通过但未产生交易。运行命令：
    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 19 of the 50 V11 endpoints that take a request body, not just refunds and documents. 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; 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. 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.
  • V11的成功判断条件是
    ResponseCode == 0
    ，而非
    DealResponse == 0
    。
    DealResponse
    在V11中不存在；基于旧版Cardcom示例训练的工具会错误地使用该字段。每个V11端点都会返回
    ResponseCode
    和
    Description
    字符串。
  • DocumentTypeToCreate
    是STRING枚举（
    "TaxInvoiceAndReceipt"
    、
    "TaxInvoice"
    、
    "Receipt"
    等），而非整数代码。整数文档代码如
    101
    或
    400
    属于旧版
    .aspx
    接口，不适用于V11。
  • TerminalNumber
    必须以整数形式发送，而非字符串。工具通常会错误地将其用引号包裹。
  • 在50个接收请求体的V11端点中，有19个需要
    ApiPassword
    ，而不仅仅是退款和文档操作。企业级的读取和写入操作需要该密码（
    ListTransactions
    、
    SpecialTransactions
    、
    RefundByTransactionId
    、所有
    Documents/*
    写入操作、所有
    Financial/*
    报表操作、所有
    TapTransactions/*
    ）；单卡扣费操作不需要。
    LowProfile/Create
    或
    Transaction
    端点甚至没有该属性，因此在这些请求中发送该密码是错误的。工具通常会在
    ListTransactions
    请求中遗漏该密码，因为旧版指南称其仅用于“退款和文档操作”。
  • 报表端点
    ListTransactions
    和
    SpecialTransactions
    不接受
    TerminalNumber
    ，且两者都设置了
    additionalProperties: false
    ，因此包含该字段会导致调用失败。在
    ListTransactions
    中使用
    LimitForTerminal
    将结果限定到单个终端。它们的日期格式为
    DDMMYYYY
    字符串，且
    ListTransactions
    还需要
    Page
    和10到2000之间的
    Page_size
    。
  • 注意V11的实际字段拼写：
    ISOCoinID
    / 
    ISOCoinId
    、
    IsSendByEmail
    （而非
    SendByEmail
    ）、
    TaxId
    （而非
    VAT_Number
    ）。语言字段的拼写取决于你使用的文档对象，所有这些架构都会拒绝未知属性，因此拼写错误会直接导致调用失败：
    Document
    （独立
    CreateDocument
    ）和
    DocumentTran
    （
    Transaction
    ）使用拼写错误的
    Languge
    ，而
    DocumentLP
    （附加到
    LowProfile/Create
    的文档）使用正确拼写的
    Language
    。如果统一使用
    Languge
    ，会破坏本指南推荐的Low Profile流程。
  • 当前以色列的增值税率为18%（2025年1月生效；2026年1月将税率提高到19%的预算提案已被否决）。Cardcom在服务器端计算增值税，因此文档金额会根据
    IsVatFree
    标志处理。
  • PCI合规范围：托管的Low Profile使你处于SAQ-A合规级别。使用原始
    CardNumber
    /
    CVV2
    的服务器到服务器
    Transaction
    会处于SAQ-D合规级别。当前的标准是PCI DSS v4.0.1（2024年6月发布的有限修订版），51项未来生效的要求已于2025年3月31日生效，因此所有要求目前均已实施。除非有充分理由需要处理原始卡片数据，否则优先选择Low Profile或令牌方式。
  • 结算时间在终端上配置，而非按请求设置，且无法通过API设置。Cardcom公布了三种结算周期：月度（当月1日至月末前一天的交易，次月6日到账）、每周（周日至周五的交易，次周三到账）、双月度（1日至15日的交易，次月2日到账；16日至月末前一天的交易，次月8日到账）。在向企业承诺具体到账日期前，仍需确认商户终端上实际配置的结算周期。
  • Apple Pay和Google Pay没有像
    UrlToBit
    /
    UrlToPayPal
    那样的单独URL字段    。在管理面板中启用终端上的这些支付方式后，它们会直接在托管的Low Profile页面内显示为钱包按钮。

Troubleshooting

故障排除

Error: a non-zero 
ResponseCode
on 
LowProfile/Create

错误：
LowProfile/Create
返回非零
ResponseCode

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
.
原因：请求存在验证或认证问题。 解决方案：读取响应中的
Description
字符串，它会指明确切问题。验证
TerminalNumber
是整数且
ApiName
正确。完整的错误代码参考请查看
https://secure.cardcom.solutions/Api/v11/Docs
。

Error: "Low Profile page loads but payment fails"

错误："Low Profile页面加载但支付失败"

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.
原因：通常是
WebHookUrl
或重定向URL问题。 解决方案：确保
SuccessRedirectUrl
、
FailedRedirectUrl
和
WebHookUrl
是可公开访问的HTTPS URL。本地主机URL无法工作，开发时请使用隧道工具（如ngrok）。

Error: "Refund returns a non-zero 
ResponseCode
"

错误："退款返回非零
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
).
原因：缺少
ApiPassword
，或交易已到账但你发送了
CancelOnly: true
。 解决方案：在每个退款请求中包含
ApiPassword
。仅在交易到账前使用
CancelOnly: true
；交易到账后，请发送真实退款（省略
CancelOnly
或设置为
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.
原因：未设置
IsSendByEmail
或缺少邮箱地址。 解决方案：设置
IsSendByEmail: true
并在
Document
对象中包含有效的
Email
。检查垃圾邮件文件夹，Cardcom从其自有域名发送邮件。

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.
原因：
Transaction
请求中缺少
Document
对象。 解决方案：在每个令牌扣费请求中包含完整的
Document
对象，包括
DocumentTypeToCreate
、
Name
和
Products
。文档生成是按交易可选的功能。