cardcom-payment-gateway

Cardcom 決済ゲートウェイ

法的通知

これは、AI モデルが運営する無料の技術統合ガイドです。Cardcom API の呼び出し方法と、イスラエルの請求書発行規則との関係について説明します。このガイドの出力はすべて、税務アドバイザー、会計士、弁護士の関与、確認、承認を受けることなく、AI モデルによって自動的に生成されています。ここに記載されている内容は、税務上の見解でも専門的な助言でもありません。また、AI モデルは誤りを含んだり、データを省略したり、誤った結論を示したりすることがあります。

この統合によって作成される書類は税務書類です。正しく発行すること、報告すること、税金を納付することはお客様の責任です。拘束力のある計算を行うのは税務当局であり、税務当局への代理人としての対応は、法律で認められた者に限られます。特定の請求書に割当番号が必要かどうか、また仕入税額控除が認められるかどうかは、お客様の実際の状況に基づき、会計士が判断する事項です。サービス開始前に、税務アドバイザーまたは会計士に請求書発行の設定を確認してもらい、PCI DSS に従ってカード会員データを取り扱ってください。このスキルの出力を使用する場合は、すべてユーザー自身の責任となります。

概要

Cardcom はイスラエルの決済処理サービスで、イスラエルの税法に準拠した請求書と領収書を生成できることが大きな強みです。他のイスラエルの決済ゲートウェイが決済のみを処理するのに対し、Cardcom は決済フローの一部として税務請求書（hashbonit mas）と領収書（kabala）を自動生成できます。これらはイスラエルの事業者に法的に発行が義務付けられています。

このスキルでは、決済、トークン化、定期請求、書類発行に対応する Cardcom REST API V11 を扱います。エンドポイント名とフィールド名は、公式の V11 OpenAPI 仕様に基づいています。

公式ドキュメント： https://secure.cardcom.solutions/Api/v11/Docs（完全な OpenAPI スキーマを含むインタラクティブ API リファレンス）。2026 年時点で V11 が現行 API です。一般公開されている V12 はありません。

サポートセンター： https://support.cardcom.solutions

イスラエル市場における Cardcom： Tranzila やその他のイスラエルの決済ゲートウェイと競合しています。Cardcom は約 1.2% からの料金を公表しており、取扱量に応じて下がります。これは最低料金であり、見積もりではないため、実際の料金は Cardcom に問い合わせるようユーザーに案内してください。差別化要因は、引き続き税務書類を標準で生成できる点です。Tranzila との統合には、代わりに tranzila-payment-gateway スキルを使用してください。

手順

ステップ 1：統合パターンを選択する

パターン	カードデータの取り扱い	最適な用途
Low Profile（iframe／リダイレクト）	Cardcom がカード情報の入力を処理	ほとんどの統合、PCI 対応範囲を最小限に抑えたい場合（SAQ-A）
Transaction（サーバー間）	カードの生データまたはトークン	保存済みトークンへの課金、定期請求
CreateDocument（サーバー間）	カードデータなし	請求書／領収書の単独発行

ほとんどのイスラエルの加盟店は、初回決済とトークン作成に Low Profile を使用し、その後、定期課金には保存済みトークンを使って Transaction エンドポイントを利用します。Document オブジェクトを追加すれば、すべての決済フローで請求書を自動生成できます。

ステップ 2：認証を設定する

Cardcom API V11 の認証情報：

• TerminalNumber（整数）-- 端末 ID（1000 は Cardcom のテスト端末です。詳細は以下をご覧ください）
• ApiName（文字列）-- API ユーザー名
• ApiPassword（文字列）-- API パスワード。目安として、会社全体のデータを読み取ったり操作したりする処理には必要ですが、1 枚のカードに請求する処理には不要です。Transactions/ListTransactions、RefundByTransactionId、SpecialTransactions、Documents/CreateDocument、CancelDoc、および Financial/* レポートなどで必要です。LowProfile/Create や Transactions/Transaction のトップレベルフィールドではないため、これらには送信しないでください。必要とするスキーマは仕様の改訂によって変わるため（「注意点」を参照）、一覧を鵜呑みにせず、V11 OpenAPI 仕様でエンドポイントのリクエストスキーマにある required 配列を確認してください。

テスト環境（Cardcom 独自の開発者向けテストページ）：

• 端末 1000。この端末の API ユーザー名とパスワードは公開されていないため、Cardcom サポートに問い合わせてください。
• イスラエルのテストカード 4580280000000008（分割払いとクレジット取引に対応）、観光客向けテストカード 4580000000000000（分割払いとクレジット取引には非対応）。有効期限は未来の日付、CVV は 123、ID 番号は任意の番号を使用してください。
• テストカードでは、5,000 NIS 未満の金額は成功、5,000 NIS を超える金額は失敗としてシミュレートされます。そのため、高額のテスト請求が失敗しても想定どおりであり、バグではありません。
• テスト端末での取引は、実際にカードに請求することなく、清算フロー全体を実行します。テスト端末で実際のカードを使っても請求はされませんが、金額分の与信枠（מסגרת）が 3 日間確保されるため、顧客のカードでは絶対にテストしないでください。

ApiName、ApiPassword、および保存されるすべてのトークンは秘密情報として扱ってください。 Transactions/Transaction に必要なのは TerminalNumber、ApiName、Amount だけなので、ApiName とトークンがあれば保存済みカードに請求できます。これらはサーバー専用の環境変数に保存し（Next.js では決して NEXT_PUBLIC_* を使用しないでください）、Cardcom の呼び出しはサーバーコードからのみ行ってください。また、レスポンス全体をログに記録しないでください（トークンとカード名義人の ID 番号が含まれています）。

ステップ 3：決済フローを実装する

目立たない統合（推奨）

これは2段階のプロセスです。

ステップ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": "[email protected]",
    "Products": [
      { "Description": "Product name", "UnitCost": 100.00, "Quantity": 1 }
    ]
  }
}

レスポンスは CreateLowProfileResponse です。ResponseCode == 0（成功）を確認し、失敗した場合は Description を読み取ります。成功すると LowProfileId（保存してください）と Url（顧客をリダイレクトするか、iframeとして埋め込むURL）が返されます。端末で有効になっている場合は、UrlToBit と UrlToPayPal も返されます。

Operation フィールドで動作を制御します。ChargeOnly（デフォルト）、ChargeAndCreateToken、CreateTokenOnly、SuspendedDeal、Do3DSAndSubmit があります。

Document の各行の合計は、必ず Amount と一致させてください（Cardcom：「יש לדאוג שסה"כ שורות החשבונית שווה לסכום החיוב」）。そのため、明細の価格にはVAT込みの、顧客が実際に支払う金額を入力します。不一致があると、Cardcomは請求を優先するため、カードへの課金は済んでいるのに請求書が発行されない場合があります。

ステップ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 は決済結果ではありません。仕様では「if equel zero then success , else , a develper error」と説明されています。これはリクエストの形式が正しいことを示すだけで、それ以上の意味はありません。カード決済の結果はネストされた TranzactionInfo に格納されます。仕様には「Will no be null at operations: ChargeOnly, ChargeAndCreateToken」とあり、つまりカード名義人がページを途中で離れた場合は null になります。

何かを履行する前に、次の5つすべてを満たしていることを確認してください。

1. HTTPステータスが200であること。404の場合、ResponseCode のない {"Message": "No HTTP resource was found..."} が返されるため、ResponseCode == 0 だけで分岐すると、ルーティングエラーを None として扱ってしまいます。
2. トップレベルの ResponseCode == 0 であること。
3. TranzactionInfo がnullでないこと。
4. TranzactionInfo.ResponseCode == 0 であること（説明は「if equal zero then success , 700 and 701 success for J2 and J5 transaction」です）。
5. TranzactionInfo.Amount が想定した金額と一致し、ReturnValue が独自の注文IDと一致すること。

TranzactionInfo.IsRefund / DealType も確認してください。返金も成功したトランザクションであり、単純な ResponseCode == 0 の判定を通過します。書類を要求した場合は、DocumentInfo もnullでないことが必要です。DocumentInfo: null のまま課金に成功している場合は、税務請求書を発行しないまま代金を受け取ったことを意味します（請求書の発行に失敗した場合、Cardcomは課金を優先します）。scripts/validate_cardcom_response.py --expect charge --amount <n> --return-value <order-id> --with-document はこれらすべてを適用し、安全側に倒して失敗します。

顧客が制御できる SuccessRedirectUrl にブラウザーが到達したことや、生のWebhook本文を根拠に履行してはいけません。TokenInfo には保存済みの Token と CardMonth / CardYear が含まれます。SuspendedInfo には保留中の取引情報が含まれます。

Webhookハンドラー（WebHookUrl は LowProfile/Create で必須です）： V11仕様では、このハンドラーに署名、共有シークレット、HMACは定義されておらず、ペイロードや再試行スケジュールも文書化されていません。Webhookの呼び出しはすべて、信頼できず、重複する可能性のある「何かが起きた」という通知として扱ってください。

1. 通知に含まれる LowProfileId を、LowProfile/Create から自分で保存したIDの中から探します。不明なIDは無視し、取得しないでください。
2. 自分の認証情報で GetLpResult を呼び出し、上記の5つの確認を行います。Webhook本文から金額やステータスを読み取ってはいけません。
3. 履行処理を冪等にします（検証と同じトランザクション内で注文を履行済みにする）。同じイベントが複数回届く可能性があるためです。古い IndicatorUrl インターフェイスに関するCardcomのドキュメントでは、サーバーがHTTP 200を返さない場合、最大7回再送するとされています。V11でも同様に再送されると想定してください。
4. 通知を永続ストレージに書き込んでから、HTTP 200を返します（200を返すとCardcomの再送が停止します）。Webhookが届かない可能性もあるため、通知を待つのではなく、GetLpResult で保留中の注文も定期的に確認してください。ページコードは作成から24時間後に有効期限が切れます。詳しくは references/production-checklist.md を参照してください。

その他の支払い方法

LowProfile/Create のレスポンスに含まれる UrlToBit と UrlToPayPal は、カードフォームと並べて表示できる別個の URL です。Google Pay と Apple Pay は、端末で有効にすると、ホストされたページ内にウォレットボタンとして表示されます。Apple Pay はトークンの保存や継続課金に対応していません（Cardcom：継続課金ページにボタンが表示される場合がありますが、支払いは完了できません）。そのため、ChargeAndCreateToken のサブスクリプションページでは Apple Pay で支払うことはできません。また、iframe 内で使用する場合は、Cardcom サポートを通じて Apple にドメインを登録する必要があります。詳細：references/api-endpoints.md。

ステップ 4：イスラエルの税務書類を生成する

書類の種類は、STRING 型の列挙値（整数ではありません）である DocumentTypeToCreate フィールドで設定します。よく使われる値は次のとおりです。

値	ヘブライ語	英語	使用する場面
Auto	---	Auto	デフォルト。管理パネルの設定を使用します
TaxInvoiceAndReceipt	hashbonit mas / kabala	Tax Invoice + Receipt	支払いを伴う B2C（最も一般的）
TaxInvoice	hashbonit mas	Tax Invoice	B2B。領収書を別途発行する場合
Receipt	kabala	Receipt	支払い確認のみ
TaxInvoiceAndReceiptRefund	---	Tax Invoice + Receipt Refund	TaxInvoiceAndReceipt を取り消す場合
TaxInvoiceRefund	---	Tax Invoice Refund	TaxInvoice を取り消す場合

DocumentToCreate 列挙値は全部で 25 種類あり、references/document-types.md に一覧があります。QuoteRefund と OrderRefund は存在しないため、Refund を付けた返金用の値を独自に作らないでください。

支払いフローに書類を含める場合： 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": "[email protected]",
    "IsSendByEmail": true,
    "Languge": "he",
    "ISOCoinID": 1,
    "Products": [
      { "Description": "Web development services", "UnitCost": 5000.00, "Quantity": 1 }
    ]
  }
}

レスポンスは DocumentInfo です。ResponseCode == 0 を確認し、DocumentType、DocumentNumber、AccountId、DocumentUrl（PDF へのリンク）を読み取ります。

3 つの書類オブジェクトではフィールド名の表記が異なります（Languge と Language の違い。また、ISOCoinID があるのは単独の Document のみで、Low Profile や Transaction の書類にはありません）。すべてのフィールド一覧は、注意事項と references/document-types.md を参照してください。TaxId は旧フィールド VAT_Number に、IsSendByEmail は SendByEmail に置き換わっています。

ステップ 4.5：税務請求書の割当番号（Mispar Haktzaa）

ドキュメント API に割当番号のフィールドを探さないでください。そのようなフィールドはなく、これは欠落ではありません。 Cardcom のドキュメントシステムは税務当局に接続されており、基準額を超える税務請求書を発行する際に番号自体を要求します。CreateDocument リクエストにも DocumentInfo レスポンスにも番号は含まれません。番号は「מספר הקצאה:」という見出しの下にドキュメントへ印字されるため、DocumentUrl の PDF から読み取ってください。

有効期限のある登録を済ませた後にのみ機能します。 番号がない場合、税抜金額が基準額を超える請求書について、顧客は仕入 VAT を控除できません。Cardcom のガイドは次のとおりです。

1. 事業主が税務当局の個人エリアで本人確認（הזדהות）を行います。必要に応じて登録します。
2. 会社または איחוד עוסקים は、そこで רישום פרטי תאגיד を完了します。
3. Cardcom の管理画面で、הגדרות、次に מסמכים、続いて שירות חשבוניות ישראל を選択します。確認コード（קוד אימות）を生成すると、本人確認のために税務当局の画面へ移動します。これを行えるのは事業主、または事業主からデジタル操作を許可された人のみです。
4. 「בדיקת קבלת מספר הקצאה」を押して、実際に番号が発行されることを確認します。

コードの有効期間は3 か月です。期限が切れると、請求書は番号なしで発行されます。再登録した後、番号を付けるためにドキュメントを再印刷してください。そのため、高額な請求書を発行する定期ジョブでは、サービスが有効であることを確認する必要があり、常に有効だと思い込んではいけません。エラー Not Acceptable (406) は、本人確認を行ったユーザーがその事業に関する税務当局の権限を持っていないことを意味します。事業主が「הרשאות לפעולות דיגיטליות」で権限を付与し、両方の項目「חשבוניות ישראל – אימות מספר הקצאה בחשבונית ספק」と「חשבוניות ישראל – בקשת מספר הקצאה עבור חשבונית ללקוח」を選択してください。

Cardcom の説明によると、次の場合も番号は発行されません。顧客の ID／会社番号（TaxId）が未入力の場合、供給者と顧客の会社番号が同一の場合、または税務請求書兼領収書に VAT が含まれない場合です。

基準額のスケジュール（税抜。法令では עולה על、つまり「超える」と定められています）：

適用開始日	基準額
2024 年 5 月	25,000 NIS
2025 年 1 月	20,000 NIS
2026 年 1 月 1 日	10,000 NIS
2026 年 6 月 1 日	5,000 NIS（現在適用中）

基準額は各ドキュメントの日付に基づきます。過去のドキュメント、osek patur、およびゼロ税率の請求書については、references/document-types.md を参照してください。すべて設定済みでも、番号が付与されないことがあります。第 47 条 (a2)(3) に基づき、請求書が不適切であるとの合理的な疑いがある場合、局長は番号の割当を拒否できます（事前決定（החלטה מקדמית）が行われ、2 営業日以内に審理が開かれます）。また、第 47 条 (a2)(4) により、販売業者は請求書の発行後に番号を申請できます。番号を利用する前に、ドキュメントに番号が記載されていることを確認してください。

ステップ 4.6：冪等性、Authorize と Capture の違い

すべての Transactions/Transaction 呼び出しで ExternalUniqTranId を送信してください。 これは請求に対して独自に割り当てる一意の ID です。仕様には明確に「取引の重複を防ぐため、一意の取引 ID を送信してください。同じ ExternalUniqTranId が送信された場合は、エラーコード 608 が返されます」と記載されています。これを指定しないと、Cardcom がカードに請求した後に HTTP 呼び出しがタイムアウトした場合、cron が再試行して顧客に二重請求することになります。

608 は「この ID には有効なカード応答がすでに返されている」という意味であり、「支払い失敗」を意味するものではありません。 Cardcom のトークン請求ガイダンスによると、呼び出しで請求（0）、J2（701）、または J5（700）の応答が返されると、その ID は使用済みになります。そのため、608 は資金が引き落とされたことを証明するものではありません。新しい ID で再試行してはいけません。608、タイムアウト、または結果が不明確な場合は、必ず POST /api/v11/Transactions/GetTransactionByExternalUniqTran を呼び出し、そのレコードの ResponseCode に基づいて処理してください（0 = 請求済み、700/701 = 確認または保留のみ）。請求が拒否された場合、その ID は使用済みにならないため、同じ ID で再試行できます。再送信する前に、応答を最大 7 秒待ってください。キャプチャには専用の ID を割り当て、保留時の ID を使用しないでください。

J2 と J5 は別のものであり、700/701 は顧客に何も起きていないという意味ではありません。 JValidateType は CreateTokenOnly および SuspendedDeal オペレーションに適用され、J2（予約は行わない簡易的なカード検証）または J5（カード所有者の利用限度額に金額を保留するオーソリ）を選択します。LowProfile/Create では既定値が 5 のため、AdvancedDefinition.JValidateType: 2 を送信しない限り、CreateTokenOnly ページでは Amount の金額が J5 で保留されます。受け取った TokenInfo.TokenApprovalNumber を Advanced.ApprovalNumber に設定してトークンに請求すると、J5 をキャプチャできます（仕様：「J5（オーソリ）リクエストをキャプチャする」）。キャプチャされなかったオーソリでは、期限が切れるまで顧客の資金が保留されたままになります。そのため、J5 を使用する場合は、キャプチャ手順と保留解除の手段が必要です（Cardcom のドキュメントでは、保留時の取引番号を指定した MTI=420 が説明されています。テスト端末では J5 を実行できません。references/production-checklist.md を参照してください）。

ステップ 5：トークンベースの継続課金を実装する

サブスクリプションや継続課金（hora'ot keva）について、Cardcom は 2 種類の方法に対応しています。

• カードベースの継続課金：保存済みのクレジットカードの Token に対して、スケジュールに従って課金します。このステップで説明します。
• MASAV 銀行口座からの自動引き落とし：顧客のイスラエルの銀行口座から直接引き落とします。RecuringPayments エンドポイント（RecuringPayments/GetRecurringPayment、GetRecurringPaymentHistory、IsBankNumberValid）で管理します。顧客がカード決済より銀行口座からの引き落としを希望する場合や、カードを利用できない場合に使用してください。基盤となる引き落とし指示は Cardcom のダッシュボードで設定します。

カードベースの継続課金を利用するには、まず加盟店に Cardcom のトークンモジュールがあり、CVV を要求しない端末が使われていることを確認してください（CVV 必須の端末では、トークンへの課金ごとに使い捨ての J5 承認番号が必要です）。また、このモジュールがない場合、Cardcom がトークンを保持する期間は 6 か月のみです。返金については references/production-checklist.md を参照してください。

1. 初回の支払い時にトークンを作成します。 Low Profile で Operation: "ChargeAndCreateToken"（または "CreateTokenOnly"）を使用します。LowProfileResult は、Token、CardMonth、CardYear、およびトークンが Cardcom から削除される日付を示す TokenExDate を含む TokenInfo を返します。

2. トークンを安全に保存します。 Token 文字列、有効期限、カード番号の下 4 桁を保存します。トークンは端末に紐付けられています。

3. 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,
  "ExternalUniqTranId": "sub-8841-2026-10",
  "Document": {
    "DocumentTypeToCreate": "TaxInvoiceAndReceipt",
    "Name": "Subscriber Name",
    "Email": "[email protected]",
    "IsSendByEmail": true,
    "Products": [
      { "Description": "Monthly subscription", "UnitCost": 99.00, "Quantity": 1 }
    ]
  }
}

ExternalUniqTranId は、購読者 1 人につき請求サイクルごとに 1 つ設定します。同じサイクルの再試行はブロックされます（608）が、翌月の課金は実行されます。応答は TransactionInfo です。課金として扱うのは ResponseCode == 0 の場合のみです（700／701 は J2／J5 の検証結果で、課金は発生していません）。続いて TranzactionId、Token、DocumentNumber、DocumentUrl を読み取ります。Document オブジェクトを付けると、各トークン課金時に請求書を自動生成してメールで送信できます。DocumentNumber がない場合、カードへの課金は完了していますが請求書は発行されていないため、再課金せずに CreateDocument で発行してください。

ステップ 6：返金を処理する

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 を確認し、返金取引の ID である NewTranzactionId を読み取ります。

対応するクレジット伝票を発行するには、Documents/CreateDocument を呼び出し、TaxInvoiceAndReceiptRefund や TaxInvoiceRefund などの返金用 DocumentTypeToCreate を指定します。また、元の課金ではなく、DealNumbers: [{"DealNumber": <NewTranzactionId>}] を使って REFUND 取引に紐付けます。Cardcom の旧インターフェースに関する返金ガイドにも、返金後にドキュメント API を再度呼び出し、返金取引に紐付けるよう明記されています。同じ返金に対して Documents/CancelDoc も呼び出さないでください。その仕様概要は「Cancel document and refund credit card」であり、ApiName、ApiPassword、DocumentNumber、および INTEGER 型の DocumentType を受け取り、NewDocumentNumber を返します。そのため、RefundByTransactionId と併用すると二重返金になるおそれがあります。ドキュメントが発行済みの販売を全額返金する場合は、CancelDoc のみを使う方法が、ドキュメントと連動した代替手段です。AllowMultipleRefunds（デフォルトは false）を使って、同じ取引への二重返金を防止してください。

ステップ 6.5：レポート用の取引を照会する

取引を指定期間で取得する場合（照合、月次レポート、ダッシュボードなど）：

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
}

ApiPassword、FromDate、ToDate（DDMMYYYY 形式の文字列。たとえば 01062026 は 2026 年 6 月 1 日です）、Page（1 から）および Page_size（10～2000）はすべて必須です。TerminalNumber フィールドはありません。LimitForTerminal を使って端末を絞り込みます。

レスポンスは GetTranzactionsResp です。ResponseCode == 0 を確認してから、Tranzactions（TransactionInfo の配列）と、エコーされた Page および Page_size を読み取ります。Page_size より行数が少ないページが返されるまで、次のページを要求してください。

Transactions/SpecialTransactions は名前とは異なり、読み取り専用のエンドポイントです（references/api-endpoints.md を参照）。

ステップ 7：保留取引（後払い請求）

保留取引では、すぐに請求を行わずに支払いインテントを承認します。

1. Operation: "SuspendedDeal" を指定して Low Profile セッションを作成します。
2. LowProfileResult は SuspendedDealId を含む SuspendedInfo を返します。
3. 後から Cardcom 管理パネル、または POST /api/v11/SuspendedDeals/Charge で請求します。このエンドポイントのフィールドは TerminalNumber、ApiName、SuspendedDealID のみで、すべて必須です（additionalProperties: false）。大文字・小文字に注意してください： 結果オブジェクトでは SuspendedDealId、リクエストでは SuspendedDealID と表記されます。リクエスト側の表記を送信してください。SuspendedDeals/Cancel と GetSuspendedDealInfo にも同じ 3 つのフィールドを渡します。このグループには GetSuspendedDeals と UpdateSuspendedDealInfo もあります。

事前承認や、サービス提供後に請求するサービスに便利です。ここでも JValidateType が適用され、LowProfile/Create ではデフォルトが 5（J5）です。そのため、通常、保留取引ではカード上で金額が確保されます。請求しない取引はキャンセルしてください。

ステップ 8：エラーを処理する

このスキルが使用するすべてのエンドポイントは、整数の ResponseCode と文字列の Description を返します（GetTransactionInfoById や CompanyOperations の照会など、一部のエンドポイントは代わりに配列またはブール値を直接返します）。ResponseCode == 0 は成功を意味します。ゼロ以外の値は開発者エラーまたは取引エラーを示し、Description に人が読める理由が記載されています。

import requests

BASE = "https://secure.cardcom.solutions/api/v11"
payload["ExternalUniqTranId"] = order_id  # same id on every retry of THIS charge

try:
    r = requests.post(f"{BASE}/Transactions/Transaction", json=payload, timeout=30)
except requests.RequestException:
    r = None  # outcome unknown: the card MAY have been charged

if r is None or r.status_code != 200:
    # Never re-charge blind. Ask Cardcom whether the charge went through.
    q = requests.post(f"{BASE}/Transactions/GetTransactionByExternalUniqTran",
                      json={"TerminalNumber": payload["TerminalNumber"],
                            "ApiName": payload["ApiName"],
                            "ExternalUniqTranId": order_id}, timeout=30)
    resp = q.json() if q.status_code == 200 else None
else:
    resp = r.json()

code = resp.get("ResponseCode") if resp else None
if code == 0:
    deal_id = resp["TranzactionId"]
elif code == 608:
    mark_for_lookup(order_id)  # id already answered: look the record up, never re-charge
else:
    log_error(f"Cardcom error {code}: {resp.get('Description') if resp else 'no response'}")

HTTP ステータス（リクエストが受信されたことを示す 200）と ResponseCode（操作の成功を示す 0）の両方を必ず確認してください。ApiName／ApiPassword はサーバー側にのみ保持してください。これらの呼び出しをブラウザーの JavaScript から実行してはいけません。数値エラーの一覧は公式ドキュメント https://secure.cardcom.solutions/Api/v11/Docs に記載されています。エラーコードとメッセージの対応をハードコードせず、代わりに Description を読み取ってください。処理パターンについては references/api-responses.md を参照してください。

例

例 1：請求書を発行する EC サイトのチェックアウト

ユーザー：「イスラエルの EC サイトで支払いを受け付け、税務請求書を自動発行したいです」 操作：

1. DocumentTypeToCreate: "TaxInvoiceAndReceipt" を指定して Low Profile を選択します。
2. Document オブジェクトに商品詳細を設定し、LowProfile/Create で Low Profile ページを作成します。
3. LowProfile/GetLpResult を呼び出す WebHookUrl ハンドラーを実装します。 結果：顧客が支払うと、ハシュボニット・マス／カバラが自動生成され、PDF としてメールで送信されます。

例 2：月次 SaaS サブスクリプション

ユーザー：「SaaS 製品を運営しています。ユーザーに毎月 149 NIS を請求し、請求書を送りたいです」 操作：

1. 初回の支払い：Operation: "ChargeAndCreateToken" を指定して LowProfile/Create を実行します。
2. TokenInfo から Token、CardMonth、CardYear を保存します。
3. 毎月の cron：トークン、その請求サイクル専用の新しい ExternalUniqTranId、および Document オブジェクトを指定して Transactions/Transaction を実行します。 結果：月次の請求書発行を伴う自動継続課金が実現します。

例 3：支払い処理なしの単独請求書

ユーザーの発言：「すでに銀行振込で受け取った支払いについて、税務請求書を発行したいです」 操作：

1. Documents/CreateDocument を使用します（支払い処理は行いません）。
2. DocumentTypeToCreate: "TaxInvoice" を設定します。
3. Name、TaxId、Products[] を含め、IsSendByEmail: true として顧客のメールアドレスを指定します。 結果：クレジットカード処理を行わずに税務請求書が作成され、メールで送信されます。

例 4：クレジットノートを発行して返金する

ユーザーの発言：「注文 #5678 の返金を希望されています。クレジットノートも発行する必要があります」 操作：

1. TransactionId と ApiPassword を指定して Transactions/RefundByTransactionId を呼び出します。
2. ResponseCode == 0 を確認し、NewTranzactionId を読み取ります。
3. DocumentTypeToCreate: "TaxInvoiceAndReceiptRefund" と DealNumbers: [{"DealNumber": <NewTranzactionId>}] を指定して Documents/CreateDocument を呼び出します。 結果：返金が処理され、対応するクレジット文書が作成されます。

例 5：Bit、Apple Pay、Google Pay に対応する

ユーザーの発言：「クレジットカードに加えて、Bit、Apple Pay、Google Pay でも顧客が支払えるようにしたいです」 操作：

1. 端末で各決済方法を有効にしてから、通常どおり Low Profile ページを作成します。
2. カードフォームの横に UrlToBit を表示します。Apple Pay と Google Pay はページ内に表示されます（Apple Pay が利用できるのは単発課金のみで、トークンを作成するページでは利用できません）。 結果：顧客が決済方法を選択でき、ウェブフローは同じです。

コミュニティライブラリ

• @tsdiapi/cardcom（TypeScript/Node.js）-- コミュニティ製の V11 クライアントです。当方ではレビューしていません。npm install @tsdiapi/cardcom
• CardCom/OpenFields-FrontEnd-React および CardCom/OpenFields-Backend-Node -- Cardcom 公式の OpenFields サンプル（リンクは以下）。

参考リンク

リソース	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

同梱リソース

リファレンス

• 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 オブジェクトのフィールド一覧、イスラエルの税法に基づく VAT の取り扱いを記載しています。生成する文書タイプの判断時に参照してください。
• references/production-checklist.md -- サブスクリプションの前提条件、文書の合計額、J5 のリリース、ウェブフックの状態、冪等性、シークレットについて記載しています。本番稼働前にお読みください。
• references/domain-checklist.md -- このスキルのレビューで使用する網羅性チェックリストです。

スクリプト

• scripts/validate_cardcom_response.py -- Cardcom V11 API のレスポンスを検証します。LowProfileResult またはフラットなレスポンス（Transaction、CreateDocument、RefundByTransactionId）に対応しています。--expect {charge,token,document,refund,validation} を指定すると、期待される結果がない場合に処理を失敗させます。--amount と --return-value では注文との照合を行い、--with-document は請求書が発行されていない課金を失敗として扱います。成功とみなされるのは ResponseCode 0 のみです。700/701 は、J2/J5 カードチェックが成功したものの課金は行われていないことを意味するため、--validation-only を指定しない限り拒否されます。608 は重複としてブロックされたことを報告します。実行方法：python scripts/validate_cardcom_response.py --help

注意点

• V11 の成功判定は ResponseCode == 0 であり、DealResponse == 0 ではありません。V11 に DealResponse は存在しません。古い Cardcom の例で学習したエージェントは、これを作り出してしまいます。このスキルのエンドポイントは、ResponseCode と Description 文字列を返します。
• Document オブジェクトの DocumentTypeToCreate と、CreateDocumentUrl の DocumentType は文字列の列挙値（"TaxInvoiceAndReceipt"、"TaxInvoice"、…）です。ただし、複数の V11 ドキュメントエンドポイントでは整数型を使います。該当するのは CancelDoc.DocumentType、SendAllDocumentsToEmail.DocumentType、GetReport.DocType、および CrossDocument のフィールドです。仕様には整数と名前の対応表が公開されていないため、推測せず、Cardcom から取得するか、すでに持っているドキュメントから値を取得してください。
• TerminalNumber は文字列ではなく整数として送信する必要があります。エージェントはよく引用符で囲んでしまいます。
• ApiPassword の一覧は仕様の改訂ごとに変わるため、決して記憶を頼りに回答しないでください。 以前、このスキルでは Documents/ExternalShopCreateDocument に ApiPassword は不要と記載していましたが、現在の仕様では必須です。また、記載されていた TapTransactions のパスはなくなっています。エンドポイントのスキーマを確認してください。逆のケースとして、LowProfile/Create や Transactions/Transaction のトップレベルフィールドに ApiPassword はありませんが、元の TransactionId がない場合のトークンまたはカードによる返金経路で、IsRefund／IsRefundDeal を設定するには、Advanced／AdvancedDefinition 内で ApiPassword が必須です。
• Webhook は認証されていません。 LowProfile/Create のどこにも署名やシークレットのフィールドはなく、WebHookUrl は任意ではなく必須のフィールドです。URL を知っている人なら誰でも POST できるため、Webhook がトリガーできるのは、作成した LowProfileId に対する GetLpResult の照会（ステップ 3b）だけにしてください。
• レポート用エンドポイントの ListTransactions と SpecialTransactions は TerminalNumber を受け付けず、どちらのスキーマにも定義されていません（どちらも additionalProperties: false に設定されています）。そのため、送信しないでください。ListTransactions では LimitForTerminal を使って端末を指定します。日付は DDMMYYYY 形式の文字列です。また、ListTransactions では Page と、10～2000 の範囲の Page_size も必須です。
• V11 での実際のフィールド名に注意してください。ISOCoinID／ISOCoinId、IsSendByEmail（SendByEmail ではありません）、TaxId（VAT_Number ではありません）。言語フィールド名は、どのドキュメントオブジェクトを使うかによって異なり、各スキーマにはそれぞれのオブジェクトで使う綴りだけが定義されています（additionalProperties: false）。そのため、もう一方の綴りは無視される可能性が高いです。 単独の CreateDocument の Document と、Transaction の DocumentTran では、誤記された Languge を使います。一方、LowProfile/Create に添付するドキュメントの DocumentLP では、正しい綴りの Language を使います。どこでも Languge を適用すると、Low Profile ドキュメントの言語が意図したとおりに設定されません。
• 現在のイスラエルの VAT 税率は 18％です（2025 年 1 月適用。それ以前は 17％だったため、過去の期間を対象にドキュメントを再発行する場合は、対象日当時の税率を使う必要があります）。Cardcom はサーバー側で VAT を計算するため、ドキュメントの金額は IsVatFree フラグに従って処理されます。
• PCI の対象範囲：ホスト型の Low Profile を使うと、SAQ-A の範囲内にとどまります。生の CardNumber／CVV2 を使うサーバー間の Transaction は、SAQ-D の対象になります。現行規格は PCI DSS v4.0.1 です。将来適用予定だった 51 項目の要件は、2025 年 3 月 31 日から適用されています。生のカードデータを扱う実際の理由がない限り、Low Profile またはトークンを優先してください。
• 精算のタイミングはリクエストごとではなく端末で設定され、API から設定することはできません。Cardcom では、月次、週次、月 2 回のサイクルが案内されています（references/api-endpoints.md に日付があります）。特定の日を約束する前に、加盟店の端末に設定されているサイクルを確認してください。

トラブルシューティング

エラー：LowProfile/Create で ResponseCode がゼロ以外

原因：リクエストに検証または認証の問題があります。 解決策：レスポンスの Description 文字列を確認してください。具体的な問題が記載されています。TerminalNumber が整数であることと、ApiName が正しいことを確認してください。数値エラーの完全なリファレンスは https://secure.cardcom.solutions/Api/v11/Docs にあります。

エラー：「Low Profile ページは読み込まれるが、決済に失敗する」

原因：テスト端末では、5,000 NIS を超えるテストカードの金額は失敗としてシミュレートされます（Cardcom のテストページ）。それ以外の場合、カードの結果は TranzactionInfo.Description に記載されています。このスキルでは、その他の原因は確認できていません。 解決策：5,000 NIS 未満でテストし、GetLpResult から TranzactionInfo.ResponseCode と Description を確認してください。Cardcom のドキュメントでは、外部（localhost 以外）の HTTPS リダイレクト URL と通知 URL が必要とされているため、開発時はトンネルを使用してください。

エラー：「返金で ResponseCode がゼロ以外になる」

原因：ApiPassword が指定されていないか、取引がすでに入金処理済みなのに CancelOnly: true を送信しています。 解決策：返金リクエストには毎回 ApiPassword を含めてください。入金処理前に限り CancelOnly: true を使用してください。入金処理後は、実際の返金を送信してください（CancelOnly を省略するか、false に設定します）。

エラー：「請求書は作成されたが、メールで送信されない」

原因：IsSendByEmail が明示的に false に設定されている（デフォルトは true）か、Email が指定されていないか無効です。 解決策：IsSendByEmail は true のままにし、Document オブジェクトに有効な Email を含めてください。迷惑メールフォルダーを確認してください。Cardcom は自社ドメインからメールを送信します。

エラー：トークン決済で ResponseCode が 608

原因：有効なカード応答が返された呼び出し、つまり決済または J2/J5 チェックで、同じ ExternalUniqTranId がすでに使用されています（仕様：「同じ ExternalUniqTranId を送信すると、エラーコード 608 が返されます」）。 解決策：新しい ID で再決済しないでください。Transactions/GetTransactionByExternalUniqTran を呼び出し、そのレコードの ResponseCode に基づいて処理を分岐してください。0 は顧客がすでに決済済みであることを示し、700/701 は前回の呼び出しが J2/J5 チェックのみだったことを示します。

エラー：「トークン決済は成功したが、請求書がない」

原因：Transaction リクエストに Document オブジェクトがありません。 解決策：トークン決済ごとに、DocumentTypeToCreate、Name、Products を含む完全な Document オブジェクトを指定してください。書類の生成は取引ごとにオプトインする必要があります。