tranzila-payment-gateway

Tranzila 決済ゲートウェイ

概要

Tranzila は、1999 年から運営されているイスラエル有数の決済処理会社（solek）です。イスラエルのカード処理基盤の中核である Shva ネットワーク（reshet shva）に接続し、イスラエルのすべてのカード発行会社（Isracard、Visa Cal、Max（旧 Leumi Card））に対応しています。

このスキルでは、イスラエルのアプリケーションでクレジットカード決済（slikat kartis ashrai）を受け付けるための、Tranzila との連携方法を説明します。

公式ドキュメント： https://docs.tranzila.com/

テスト用認証情報： ご利用の端末のサンドボックス用カード番号について、Tranzila のサポートに問い合わせ、Tranzila ダッシュボードで端末をサンドボックスモードに設定してください。ブログ記事やこのスキルの古いバージョンで出回っているテストカードの値は、ベンダーが公開したものではないため、有効な値として扱わないでください。

手順

ステップ 1：連携パターンを選択する

ニーズに応じて、ユーザーが適切な方法を選べるようにしてください。

パターン	ヘブライ語	PCI の適用範囲	最適な用途
Iframe	daf tashlum mutman	最小（通常 SAQ A）	手早い連携、コンプライアンス対応を最小限に抑える
Hosted Fields	sdot mitarachim	小（通常 SAQ A-EP）	PCI 負担を抑えた、カスタマイズ可能なチェックアウト UX
API V2（サーバー間）	sharat le-sharat	最大（通常 SAQ D）	トークン決済、定期決済、返金

SAQ の対応関係は Tranzila ではなく PCI Security Standards Council によるもので、適用資格は加盟店の環境全体やアクワイアラーの要件によって異なります。そのため、連携方法を選べば自動的に適用されると思い込まず、必ず確認してください。また、PCI DSS v4 では決済ページのスクリプト要件（6.4.3 および 11.6.1）が厳格化され、SAQ フォームも v4.x 向けに再発行されています。「iframe なら対応不要」という前提が今も通用すると考えず、PCI SSC のドキュメントライブラリで最新の SAQ A を確認してください。

イスラエルの加盟店の多くは、決済の受付に Iframe を使い始め、その後、トークン決済や返金などのサーバー側操作に API V2 を使用します。

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

Tranzila では、連携方法に応じて異なる認証情報を使用します。

Iframe / Legacy CGI の場合：

• supplier -- 端末名（Tranzila から提供）
• TranzilaPW -- 取引パスワード

API V2（api.tranzila.com/v1）の場合： 認証には 4 つのヘッダーを使う HMAC-SHA256 ハンドシェイクが必要です。単一のキー用ヘッダーではありません。すべてのリクエストで、次の 4 つをすべて送信する必要があります。

• X-tranzila-api-app-key -- 公開アプリケーションキー
• X-tranzila-api-request-time -- 現在の Unix 時刻（秒単位）
• X-tranzila-api-nonce -- ランダムなノンス（約 40 バイト）
• X-tranzila-api-access-token -- hmac_sha256(secret + request_time + nonce, app_key)（リクエスト時刻とノンスを連結した値をキーとして、アプリケーションキーに対して計算する HMAC-SHA256）

API V2 に登録すると、公開アプリケーションキーと秘密鍵の両方が発行されます。X-tranzila-api-app-key だけを送信するリクエストは拒否されます。（ベース URL は https://api.tranzila.com です。主要な決済エンドポイントは /v1 以下にあり、「API V2」は認証方式の世代を指しますが、継続決済の作成など一部の新しいエンドポイントでは /v2 のパスが使われます。）本番環境にリリースする前に、docs.tranzila.com の認証ページで正確な連結順序を確認してください。

認証情報は安全に保管するよう（環境変数やシークレットマネージャーを使用）、またソース管理に決してコミットしないよう、ユーザーに注意してください。

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

オプション A：Hosted Fields（カスタム UX におすすめ）

Hosted Fields を使うと、カード情報の入力を Tranzila が安全に処理する一方で、独自のチェックアウトフォームを設計できます。

1. ページに Tranzila Hosted Fields JS を含めます
2. カード番号、有効期限、CVV 用のコンテナー <div> 要素を作成します
3. ターミナル名とスタイル設定を指定してフィールドを初期化します
4. 送信時に、カード情報をサーバーに渡すことなく、JS が TranzilaTK トークンを生成します
5. API V2 経由で課金するため、トークンをバックエンドに送信します

これにより、SAQ-A-EP PCI 準拠を維持しながら、デザインを完全に制御できます。https://docs.tranzila.com/ の Payments & Billing インデックスから、Hosted Fields のセクションを参照してください（詳細なスラッグパスは頻繁に変わります）。

Webhook の署名検証。 Tranzila が結果を通知ページ（iframe の notify_url_address、Bit API の notify_url）に POST する際、受信データの形式だけを見て信用してはいけません。ベンダーが実際にドキュメント化している仕組みで検証してください。Payments and Billing セクションのドキュメントにある Hosted Fields の Response Hash 機能（独自のシークレットを使って response_hash を生成し、受信時に再計算できます）、または Handshake API V2 フローを使用します。フォームフィールドに独自のチェックサムを含め、受信時に検証する方法も、許容できる代替策です。myid の往復だけに頼ったり、存在しない確認エンドポイントを作り上げたりしてはいけません。この手順がなければ、URL を知った人なら誰でも、取引が成功したように見せかけたコールバックを偽造できます。

コールバックとリダイレクトのパラメーター名は、製品によって異なります。 iframe では success_url_address、fail_url_address、notify_url_address を使います（「Notify」ページには、実際に行われた取引のデータが送信されます）。notify_url という名前を使うのは Hosted Fields、3DS API、Bit です。iframe では、このパラメーターは使用されません。iframenew.php に notify_url を送信すると、Webhook は一切届かず、顧客への課金は完了するものの、注文は処理されません。

オプション B：Iframe 統合（クイックスタート）

1. チェックアウトページに Tranzila iframe を埋め込みます。

   • URL：https://direct.tranzila.com/{supplier}/iframenew.php
   • クエリパラメーターを追加します：sum、currency、cred_type
   • tranmode でモードを選択します：A は通常の課金（デフォルトの動作）、V は検証（J5）、N は検証（J2）、K は課金せずにトークンを作成します。また、トークンを作成するモードには AK、VK、NK があります。J4 モードはなく、トークンの作成を指定しない限り iframe はトークンを作成しません

2. notify_url_address で応答を処理します。

   • Tranzila が結果をサーバーに POST します
   • Response フィールドを確認します：000 = 承認
   • 今後の課金に備えて TranzilaTK（トークン）を保存します

3. サーバー側で取引を確認します（推奨）。

   • 三者間ハンドシェイクを使って、取引が本物であることを検証します

オプション C：API V2 によるサーバー間通信

トークンへの課金、返金、カード情報の入力を伴わない操作の場合：

トークンに課金する：

POST https://secure5.tranzila.com/cgi-bin/tranzila31tk.cgi
Content-Type: application/x-www-form-urlencoded

supplier={terminal}&TranzilaPW={password}&TranzilaTK={token}&expdate={MMYY}&sum={amount}&currency=1&cred_type=1

返金を処理する： 返金は独自のエンドポイントで処理され、課金リクエストでは使わない認証情報が必要です。

• レガシー CGI： tranmode=C{index}（元の取引のインデックス）に加え、supplier、sum、currency、TranzilaTK、expdate、cred_type、TranzilaPW、CreditPass、authnr を指定して、https://secure5.tranzila.com/cgi-bin/tranzila71u.cgi に POST します。CreditPass は Tranzila から取得し、ターミナルで有効化する必要がある別個のクレジットパスワードです。そのため、エンドツーエンドで一度もテストしていない返金フローは、たいてい最初にここで失敗します。
• API V2： txn_type を credit（返金）、cancel（デビットまたはクレジットのキャンセル）、reversal（J5 で確保した与信枠の解放）のいずれかに設定し、元の取引を reference_txn_id で指定して、POST https://api.tranzila.com/v1/transaction/credit_card/create を実行します。

コードを書く前に、どちらを使用するか決めてください。パラメーター名はそのまま引き継げません。

完全なパラメーター一覧は references/api-parameters.md を参照してください。

ステップ 4：イスラエル固有の決済タイプへの対応

イスラエルの決済には、国際的な決済処理とは異なる固有の特徴があります。

分割払い（Tashlumim）：

• 分割払いには cred_type=8 を設定します（cred_type=6 はカード会社独自のクレジットプランであり、別の商品です）。
• パラメーター：npay（支払回数から 1 を引いた数）、fpay（初回の支払額）、spay（2 回目以降の支払額）
• fpay + (npay * spay) の合計は、合計金額 sum と一致する必要があります。
• すべての端末が分割払いに対応しているわけではありません（端末で有効化されていない場合はエラーになります。正確なコードは公式の表で確認してください）。

クレジットタイプ（cred_type）：

値	タイプ	ヘブライ語
1	クレジットカードによる通常の一括払い	ashrai ragil
6	クレジット（kredit）、カード会社独自のクレジットプラン	kredit
8	分割払い	tashlumim

現在の iframe パラメーター表に記載されている値は、この 3 つのみです（「1 - Credit card, 6 - Credit, 8 - installments」）。このスキルの以前のバージョンでは 2、3、5、9 も記載していましたが、これらはベンダーのドキュメントに記載されておらず、送信するとコード 017（この取引では許可されていないクレジットタイプ）が返されます。

通貨コード（matbea）：

コード	通貨	ヘブライ語
1	ILS（シェケル）	shekel chadash
2	USD	dolar
978	EUR	euro
826	GBP	lira sterling

ユーロとスターリングには、小さな整数ではなく ISO 4217 の数値コードを使用します。このスキルの以前のバージョンでは 3 = GBP、7 = EUR と記載していましたが、どちらの値もベンダーのパラメーター表に記載されておらず、送信するとコード 016（許可されていない通貨）が返されます。

これらのパラメーター名は、iframe とレガシー CGI のものです。 API V2 では、同じ概念に異なるフィールド名と型を使用します。txn_currency_code には、数値の currency ではなく、ISO のアルファベットコード（ILS、USD、EUR、GBP など）を指定します。分割払いプランには、cred_type と npay / fpay / spay ではなく、payment_plan と installments_number、first_installment_amount、other_installments_amount を使用します。有効期限には、MMYY 形式の expdate ではなく、整数の expire_month と expire_year を使用します。また、カード名義人の ID には myid ではなく card_holder_id を使用します。パラメーター名をそのまま流用する前に、どのインターフェースを統合するのかを決めてください。

イスラエルの ID（teudat zehut）： 一部の取引では、9 桁のイスラエル ID 番号（mispar zehut）である myid パラメーターが必要です。これは通常のフィールドではなく、規制対象の個人情報として扱ってください。プライバシー保護法とその改正第 13 号に基づき、決済目的で収集した ID 番号には、顧客データベースの他の情報と同じ義務が適用されます。そのため、アプリケーションのログに平文で記録せず、収集目的を超えて保持せず、分析用のペイロードにも含めないでください。

DCdisable で二重請求を防止します。 Tranzila 独自の重複取引防止機能では、取引ごとに一意の値を DCdisable パラメーターに指定します。Tranzila のデータベースで、親端末単位で最長 24 時間、その値との重複を検出します。最初の取引が失敗した場合、その取引は DCdisable による照合の対象にならないため、実際の失敗後に再試行しても処理されます。my.tranzila の「Additional Fields for Transaction」でフィールド 20 として、親端末と子端末の両方で有効化する必要があり、値は最大 254 文字です。端末が対応していない独自のアプリケーション側冪等性方式を考案するのではなく、これを使用してください。結果を確認できなかったリクエストを再試行することが、顧客への二重請求が発生する典型的な原因です。

J5 のオーソリは売上確定が必要です。 verify_mode=5（J5）は、請求を行わず、金額分の利用限度額を確保します。実際の請求は txn_type=force を指定する別の呼び出しで行い、回収しないと決めた場合は txn_type=reversal で利用限度額を解放します。J5 で開始したサブスクリプションで売上確定を実行しなければ、初回の支払いは回収されません。 知っておきたい iframe の追加機能。 bit_pay=1 を指定すると、iframe に Bit の支払いオプションが追加されます。これは、iframe を利用する加盟店にとって、Bit API を全面的に統合する代わりに使える簡単な方法です。maxpay は分割払いの最大回数を設定します。ベンダーのルールは明確で、npay、fpay、spay のいずれか、または maxpay を指定し、両方を同時に指定してはいけません。

ステップ 5：定期支払い用のトークン化を実装する（hora'ot keva）

トークン（asmachta）を使うと、カード情報を再度扱わずに、リピーターに請求できます。

1. 初回の支払い時にトークンを作成する：

   • iframe：tranmode=K（トークンのみ）、または AK／VK（請求または認証とトークン）を渡して、TranzilaTK を取得します
   • API：tranmode=K（トークンのみ）、VK（認証＋トークン）、または AK（請求＋トークン）を使用します

2. トークンを安全に保存する：

   • トークンは不透明な文字列として扱います。ベンダーは固定の長さや形式を公開していません。また、API V2 のドキュメントに記載されたトークンは英数字で、従来の CGI のトークンより長いため、長さで検証したり、末尾 4 桁がカードと一致すると想定したりしてはいけません
   • トークン、有効期限、カード番号の末尾 4 桁をデータベースに保存します
   • トークンは端末の認証情報がなければ価値がありません
   • 認証後は CVV／CVV2 を絶対に保存せず、カード番号全体も保存しないでください。 PCI DSS 要件 3.3.1 では、取引の認証後に機密認証データ（CVV、磁気ストライプまたはチップの全データ、PIN）を、暗号化していても保持することを禁止しています。保存するのはトークン、有効期限、末尾 4 桁のみです。これは、選択した統合方式にかかわらず適用され、加盟店がコンプライアンスを維持できなくなる最も一般的な原因です

3. 後からトークンに請求する：

   • /cgi-bin/tranzila31tk.cgi エンドポイントを使用します
   • TranzilaTK、expdate、sum、currency を含めます

ステップ 6：3D Secure を追加する（必要な場合）

3D Secure V2 はカード保有者の認証機能を追加します。リダイレクト方式のフロー全体については、references/3ds-flow.md を参照してください。主なポイント：

• 3DS を導入すると、支払いフローに銀行認証のステップが加わります
• 応答には認証ステータスに関する追加フィールドが含まれます
• イスラエルの一部の発行会社は、すべての種類のカードで 3DS に対応しているとは限りません

ステップ 7：Bit の支払いを受け付ける

Tranzila は、カード決済 CGI のフラグではなく、専用の Bit API を通じて、イスラエルで人気のモバイル決済アプリ Bit に対応しています。API V2 の他の機能と同じ 4 ヘッダーの HMAC 認証を使用し、https://api.tranzila.com/v1 配下に専用の Bit - Init と Bit - Refund の POST エンドポイントがあります。

1. API 経由で Bit Init エンドポイントを呼び出します。Tranzila から Bit の支払い URL が返されます
2. 顧客を Bit の URL にリダイレクトするか、QR コードを表示します
3. 顧客が Bit アプリで支払いを承認します
4. Tranzila から notify_url（Bit API での名称）に結果が送信されます
5. Bit の返金には、カード決済の返金フローではなく、専用の Bit Refund エンドポイントを使用します

Bit の制約（ドキュメントより）： NIS のみ対応し、取引金額は 5 NIS を超える必要があります。また、加盟店には Visa または Isracard の識別子が必要です。現時点では、Max のみを利用する加盟店は Bit を利用できません。 Bit は Hosted Fields や 3DS に対応していません。従来の CGI に bit=1／bit_url のパラメーターがあるとは想定しないでください。iframe では bit_pay=1 を指定して Bit を有効にします。サーバーサイド統合では、専用の Bit API を使用してください。Bit の仕様については、https://docs.tranzila.com/ のドキュメントインデックスから「Payments & Billing」セクションに移動してください（Bit の詳細なスラッグ URL は変更されることがあり、空のスタブの場合もあります）。

ステップ 8：支払い依頼リンクを生成する

Payment Requests（TRAPI）を使うと、チェックアウトページを作成せずに、メールまたは SMS で支払いリンクを送信できます。

1. 金額、説明、顧客の連絡先を指定して、API 経由で支払い依頼を作成します
2. Tranzila が安全な支払いリンクを生成します
3. リンクを顧客に送信します（Tranzila にメール／SMS で自動送信させることもできます）
4. 顧客がリンクをクリックし、Tranzila がホストするページで支払います
5. Webhook 経由で結果を受け取ります

これは、請求書の発行、電話での注文、または埋め込みフォームを使わずに支払いを受け取る必要があるあらゆる場面で便利です。

ステップ 9：継続課金（定期支払い）を設定する

単純なトークン課金を超える自動定期請求には、Tranzila の継続課金機能を利用できます。

1. 支払いスケジュール（金額、頻度、開始日／終了日）を指定して継続課金を作成します
2. Tranzila がスケジュールに従って顧客に自動で課金します
3. Reports API または Webhook 通知で結果を監視します
4. API を使用して継続課金をキャンセルまたは変更します

継続課金は有料機能です。端末で利用できるようにするには、Tranzila にお問い合わせください。継続課金の詳しい設定手順については、Tranzila のドキュメントを参照してください。

ステップ 10：請求書を生成する

Tranzila には、イスラエル税務当局が承認するデジタル署名付き税務書類を生成するための Invoicing API があります。

1. 取引に紐づけた請求書、または単独の請求書を作成します
2. 税務コンプライアンスのため、請求書にはデジタル署名が付与されます
3. 税務請求書、領収書、クレジットノートに対応しています
4. PayPal の支払いに対して自動生成できます

イスラエル税務当局の割当番号（mispar haktza'a）。一定額を超える B2B 請求書では必須です。 2024 年 5 月以降、ITA は一定額を超える B2B 税務請求書に、SHAAM から取得した割当番号を記載することを義務付けています。基準額は今日の日付ではなく、請求書自体の日付に基づきます。そのため、古い書類を再発行、移行、監査するシステムでは、次の全スケジュールを考慮する必要があります（VAT 抜きの金額）：2024 年 5 月からは NIS 25,000、2025 年 1 月からは NIS 20,000、2026 年 1 月からは NIS 10,000、2026 年 6 月 1 日からは NIS 5,000（現在適用中）。2024 年 5 月より前の日付の請求書は制度開始前のものであり、割当番号は必要ありません。法律には עולה על（超える）とあるため、基準額とちょうど同額の請求書は要件の対象外です。

これに基づいて検証を実装する場合、法律から引用した次の 2 つの制限を必ず組み込んでください。ゼロ税率または非課税の取引のみを記載した請求書は要件の対象外です。s.47(א2)(1) は לעניין חשבונית מס שהוצאה בשל עסקה שהמס שחל לגביה אינו בשיעור אפס に限って適用されるため、輸出に関する請求書には金額にかかわらず番号は不要です。また、番号がない場合の影響は明確に定められています。s.38(א1) により、BUYER による仕入 VAT の控除が認められません。לא יותר ניכוי מס התשומות הכלול בחשבונית מס שסכומה, בלא המס, עולה על 5,000 שקלים חדשים (מינואר 2026 ועד מאי 2026: 10,000 שקלים חדשים) ושאינה כוללת מספר שהקצה לה המנהל。請求書が無効になるわけではないため、そのように説明しないでください。この文言には 2 点注意してください。עולה על（超える）とあるため、基準額とちょうど同額の請求書は規則の対象外です。また、2026 年 1 月から 5 月までの期間も明記されているため、このスケジュールは事業者の概要だけでなく、法律自体から確認できます。さらに、ここには買い手からの請求を条件とする規定はありません。s.47(א2)(1) の要求は SELLER が義務に違反したかどうかを判断するものであり、買い手が控除できるかどうかを左右するものではありません。そのため、検証時に「誰も求めなかった」ことを免責の根拠として扱わないでください。Tranzila の Invoicing API で請求書を生成する場合は、現在の基準額を超える請求書について、割当番号の申請が SHAAM 経由で処理されるよう設定されているか、Tranzila サポートに確認してください。設定されていない場合は、SHAAM と連携する別の請求書発行サービス（Green Invoice、Morning など）を利用するか、ITA ポータルから割当番号を直接申請してください。

Invoicing API の全リファレンスについては、Tranzila の請求書発行ドキュメントを参照してください。

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

すべてのトランザクション結果で Response フィールドを確認してください。000 は承認を意味します。それ以外はすべて拒否またはエラーです。

API V2 呼び出しの HTTP ステータスは、トランザクションが拒否または失敗した場合でも 200 です。 HTTP 200 は成功を意味しません。実際の SHVA の結果は、本文内の Response／応答コードフィールドを確認してください。また、コード体系は 2 つに分かれています。SHVA／発行会社コード（数百種類のコードがあり、001-017 は拒否、051-089 と 101-152 は端末ベクターまたはパラメータファイルの欠落、300-354 はアクワイアラーと発行会社の権限エラー、401-406 は分割払いエラー）と、応答コードページの独立したタブにある別の 3D-Secure コード（900-930）です。Stripe やその他のゲートウェイのコードをそのまま当てはめないでください。

確認済みのコードをいくつか紹介します（残りは references/error-codes.md と、docs.tranzila.com の公式「Transaction Response Codes」ページで確認してください）。

コード	意味（ベンダーの表からの原文）	ユーザーへの対応
000	Transaction approved	トランザクションが完了しました
777	Operation completed, a success code for operations where no transaction is recorded, including J2 and J5	確認のみの呼び出しでは成功として扱います
004	Refusal. Contact the card owner to check the reason with the credit company	別のカードを試すようユーザーに依頼します
006	Incorrect identity number or CVV	ID／CVVを再入力してもらいます
012	Unauthorized card for this terminal	端末またはブランドの権限を確認します
015	Expired card. Check the expiration date again	カード情報を更新するようユーザーに依頼します
016	Unauthorized currency	端末でその通貨が有効になっていません
017	Unauthorized credit type for this transaction	カードまたは端末に対して cred_type が正しくありません
406	Transaction sum differs from first payment + fixed payment times number of payments	分割払い金額を再計算します
416	Invalid expiry date	有効期限を再入力してもらいます
425	Duplicate record	冪等性を確保し、無条件に再試行しないでください
447	Wrong credit card number	カード番号を再入力してもらいます
900	Transaction failed at the 3D Secure authentication stage (the 3DS space is 900-930, on its own tab of the response-codes page)	認証をやり直すか、許可されている場合は 3DS なしで再試行します
905	Expired card in the 3DS space (in the SHVA space, expired is 015)	カードを更新するよう顧客に依頼します
927 / 928	Card authentication cancelled by the user	顧客が認証チャレンジを中断しました。カードの不具合ではありません

コード表を記憶だけに頼ってインテグレーションに組み込まないでください。 2026 年のこのスキルの監査では、ここおよび同梱スクリプトに以前記載されていた 7 つのコード（033、036、037、039、091、125、200）が、ベンダーの表に存在しないことが判明しました。また、別の 7 つのコード（014、057、061、065、075、107、111）には、実際とは異なる意味が割り当てられていました。実際の表では、051-089 は「ベクター／パラメータファイルの欠落」、101-152 は「ベクター N のエントリー欠落」、300-354 は発行会社による拒否ではなく、アクワイアラーと発行会社の権限エラーです。発行会社による拒否は 001-017 です。必ずコードを番号で正確に検索してください。

完全なリファレンス（SHVA の表と、独立した 900-930 の 3DS コード）については、references/error-codes.md を参照し、公式ドキュメントと照合してください。コードを記憶だけに頼ってハードコードしないでください。

例

例 1：1 回限りの支払いを受け付ける

ユーザーの発言：「Node.js のチェックアウトページにクレジットカード決済を追加したいです」 アクション：

1. 選択：Iframe インテグレーション（PCI の適用範囲を最小限に抑えます）
2. 案内：サプライヤー名、金額、currency=1（ILS）を指定して iframe を埋め込みます
3. 実装：応答を取得するため、notify_url_address にサーバー側ハンドラーを設定します
4. 検証：Response=000 を確認し、ConfirmationCode を保存します 結果：埋め込みフォームを通じてイスラエルのクレジットカードを受け付けるチェックアウトが動作します。

例 2：月額サブスクリプションを設定する

ユーザーの発言：「顧客に毎月 99 NIS を自動的に請求したいです」 操作：

1. 初回決済：トークン作成用の iframe を使用します（課金とトークン化には tranmode=AK、またはカード確認とトークン化には VK）
2. 保存：レスポンスから TranzilaTK と expdate を保存します
3. 毎月：Cron ジョブから保存済みのトークンを使って tranzila31tk.cgi を呼び出します
4. 対応：期限切れのカードや拒否されたトークンを確認します 結果：トークン化されたカードを使用した月次の継続課金ができます。

例 3：分割払いを処理する

ユーザーの発言：「顧客が 6,000 NIS を 3 回のタシュルミームで支払いたいと言っています」 操作：

1. 設定：cred_type=8（分割払い）
2. 計算：fpay=2000、spay=2000、npay=2（合計 3 回払い）
3. 確認：端末で分割払いが許可されていることを確認します
4. 処理：分割払いのパラメーターを指定して取引を行います 結果：6,000 NIS の支払いが 2,000 NIS ずつの 3 回払いに分割されます。

例 4：取引を返金する

ユーザーの発言：「先週の取引を返金する必要があります。確認コードは 0283456 です」 操作：

1. まず使用する方式を決めます。従来の CGI では https://secure5.tranzila.com/cgi-bin/tranzila71u.cgi に POST します。API V2 では txn_type=credit と reference_txn_id を指定して /v1/transaction/credit_card/create に POST します
2. 従来の CGI のフィールド：元の取引のインデックスを指定する tranmode=C{index} と、supplier、sum、currency、TranzilaTK、expdate、cred_type、TranzilaPW、CreditPass、authnr を指定します。CreditPass（端末で有効にする別個のクレジットパスワード）がないと返金は失敗します
3. 設定：返金額（全額または一部）を sum に設定します
4. 確認：CGI では Response=000、API V2 では transaction_result.processor_response_code を確認します 結果：元の取引に紐付けて返金が処理されます。

例 5：Bit での支払いを受け付ける

ユーザーの発言：「ウェブサイトで Bit による支払いを受け付けたいです」 操作：

1. Bit 専用の Init エンドポイント（api.tranzila.com/v1、4 ヘッダーの HMAC 認証）を呼び出します。カード CGI のフラグではありません
2. リダイレクト：レスポンスの Bit 決済 URL に顧客を誘導します（または QR コードを表示します）
3. 対応：通知ページで支払い確認を受信します
4. 確認：Bit 決済が成功したことをレスポンスコードで確認します
5. 制約事項：NIS のみ、金額は 5 NIS 超、加盟店には Visa／Isracard の識別子が必要です（Max のみの加盟店はサポートされません） 結果：顧客はクレジットカードに加えて、イスラエルの Bit モバイルウォレットでも支払えるようになります。

例 6：SMS で決済リンクを送信する

ユーザーの発言：「電話で顧客から支払いを受け取りたいです」 操作：

1. 作成：金額と顧客の電話番号を指定して、TRAPI で決済リクエストを作成します
2. 送信：Tranzila が決済リンクを記載した SMS を自動送信します
3. 待機：顧客がリンクを開き、Tranzila のホスト型ページで支払います
4. 確認：支払い完了時に Webhook 通知を受信します 結果：チェックアウトページを構築せずに、リモートで支払いを受け取れます。

コミュニティライブラリ

• tranzilajs（TypeScript/Node.js）-- 現在も積極的に保守されている唯一のコミュニティ SDK です。HMAC 認証、Bit 決済、クレジットカード操作、iframe 生成に対応しています。インストール：npm install tranzilajs。参照先：https://github.com/NirTatcher/tranzilajs
• futureecom/omnipay-tranzila（PHP/Omnipay）-- Omnipay ドライバーのベンダー名前空間は omnipay/tranzila ではなく futureecom です（そのスラッグは Packagist で 404 になるため、古いガイドでは誤って記載されています）。採用する前にリリース日を確認してください。
• active_merchant_tranzila（Ruby）は RubyGems にありますが、リリースは 2010 年 8 月の 0.0.1 のみです。また、Tranzila は ActiveMerchant 自体にバンドルされているゲートウェイではありません。これは放棄されたものとして扱い、依存関係としてではなく、せいぜいドキュメントとして参照してください。

同梱リソース

参考資料

• references/api-parameters.md — レガシー CGI と API V2 エンドポイントの両方について、認証ヘッダー、取引パラメーター、トークン操作、分割払いのフィールドを含む、Tranzila API パラメーターの完全なリファレンスです。API リクエストの作成時や、予期しないパラメーターの動作をデバッグする際に参照してください。
• references/error-codes.md — Tranzila の応答コード（000〜999）の一覧と、それぞれの意味および推奨される対処方法です。取引で 000 以外の応答コードが返された場合に参照してください。
• references/3ds-flow.md — リダイレクトフロー、認証パラメーター、フォールバック処理を含む、Tranzila の 3D Secure V2 実装ガイドです。既存の連携に 3DS を追加する際に参照してください。

スクリプト

• scripts/validate_tranzila_response.py — Tranzila の取引応答を検証します。応答コードを確認し、必須フィールドの有無を検証して、よくある問題（確認コードの欠落、金額の不一致）を検出します。実行方法：python scripts/validate_tranzila_response.py --help

注意点

• Tranzila API はフォーム形式でエンコードされたキーと値のペアを使用します（JSON ではありません）。エージェントはデフォルトで JSON のリクエストボディを送信するため、Tranzila では拒否または無視されます。リクエストは application/x-www-form-urlencoded として送信してください。
• Tranzila のテストモードでは本番環境と同じエンドポイントを使用しますが、supplier パラメーターは異なります。エージェントが誤って、テスト取引を本番端末に送信したり、その逆を行ったりすることがあります。
• レガシー CGI の応答は、クエリ文字列と同じ形式で & によって連結されたプレーンテキストの key=value 文字列です（Response=000&ConfirmationCode=...&index=...&Tempref=...）。JSON でも、改行区切りでもありません。クエリ文字列として解析してください。一方、API V2 は JSON を返し、SHVA の結果は transaction_result.processor_response_code に、アプリケーションの error_code はその隣に含まれます。
• イスラエルのクレジットカード番号は、米国や欧州のカードとは BIN の範囲が異なります。Tranzila はカードをローカルで検証するため、Stripe やその他の国際ゲートウェイのテストカードは使用できません。
• ベンダーの一覧にないコードについて、説明してはいけません。 もっともらしく見えるコードの中には（033、036、037、039、091、125、200）、Tranzila の一覧に存在しないものがいくつかあります。それを「認識」したエージェントは加盟店に自信満々で誤った診断を伝えてしまいます。多くの場合、実際の問題は端末のベクトルやパラメーターファイルなのに、「カードの有効期限切れ」と説明してしまいます。有効期限切れのカードのコードは 015 です。
• 300 番台は拒否ではなく、権限エラーです。 300〜354 は、アクワイアラーまたは発行会社が、その取引種別、通貨、またはクレジット種別について端末を承認していないことを意味します。これは設定上の問題であり、カード所有者が再試行して解決できるものではありません。Tranzila またはアクワイアラーに問い合わせてください。
• 二重請求を明示的に防いでください。 失敗したように見えるリクエストを再試行するのはよくある反応ですが、コード 425（重複レコード）は、二重送信が事後に判明したときの状態です。最初に重複排除の方法を決め、結果を確認できていないリクエストを無条件に再試行しないでください。

参考リンク

出典	URL	確認する内容
Tranzila 開発者向けドキュメント	https://docs.tranzila.com/	API リファレンス、認証、対応カードネットワーク、3DS フロー、エラーコード
Hosted Fields の統合	https://docs.tranzila.com/ (Payments & Billing → Hosted Fields)	PCI に準拠したカード情報の埋め込み入力と、レスポンスハッシュによるコールバック整合性機能
取引レスポンスコード	https://docs.tranzila.com/docs/payments-and-billing/transaction-response-codes	SHVA および 3DS の正式なコード表。各コードは正確な番号で検索してください
認証（API V2 ヘッダー）	https://docs.tranzila.com/docs/payments-and-billing/authentication	4 つの HMAC ヘッダーと、アクセストークンの正確な導出方法
Iframe パラメーター	https://docs.tranzila.com/docs/payments-and-billing/iframe-integration	現在の cred_type、currency、tranmode の値
イスラエル税務当局の割当番号	https://www.gov.il/he/service/request-assignment-number-for-tax-invoice	請求書の日付に応じた基準額超過時に必要です。2024 年 5 月以前は不要、その後は 25,000 NIS（2024 年 5 月）、20,000 NIS（2025 年 1 月）、10,000 NIS（2026 年 1 月）、5,000 NIS（2026 年 6 月、施行中）
Tranzila 企業サイト	https://www.tranzila.com	端末の有効化依頼、分割払いの権限、連絡先、PCI 認証
tranzilajs コミュニティクライアント	https://github.com/NirTatcher/tranzilajs	コミュニティ製の TypeScript／Node クライアントと使用例

トラブルシューティング

エラー：「Transaction rejected with a non-000 response code」

原因：パラメーターの欠落または無効、カード発行会社による拒否、あるいは設定や権限の問題です。失敗時も HTTP ステータスは 200 になるため、実際のコードは Response フィールドを確認してください。 解決策：必須パラメーターがすべて指定されていることを確認してください。必須項目は supplier、TranzilaPW、sum、ccno（または TranzilaTK）、expdate です。パラメーター名が正確であること（大文字と小文字を区別）を確認してください。公式の取引レスポンスコードページ（references/error-codes.md を参照）で正確なレスポンスコードを検索し、意味を推測しないでください。

エラー：「Terminal not authorized for installments / Amex」

原因：Tranzila 端末で分割払い（または Amex）の権限が有効になっていません。 解決策：Tranzila サポート（073-222-4444）に連絡して、端末での分割払いまたは Amex の処理を有効にしてください。

エラー：「Token charge fails but iframe worked」

原因：誤ったエンドポイントの使用、または expdate の欠落がよくある原因です。 解決策：トークンによる請求には /cgi-bin/tranzila31tk.cgi（tranzila31.cgi ではありません）を使用してください。TranzilaTK と expdate の両方のパラメーターを含めてください。

エラー：「Transaction approved in test but not production」

原因：テスト用端末と本番用端末の動作は異なります。 解決策：本番用端末名とパスワードを確認してください。無効化など、一部の操作は本番環境では動作が異なります。動作に違いがある場合は Tranzila サポートに確認してください。

エラー：「Currency mismatch」

原因：通貨に対して誤ったエンドポイントを使用しています。 解決策：ILS と USD には tranzila31.cgi を使用してください。複数通貨（EUR、GBP など）には tranzila36a.cgi が必要です。