tranzila-payment-gateway

Tranzila 支付网关

概述

Tranzila 是以色列领先的支付处理商之一（solek），自 1999 年开始运营。它连接到 Shva 网络（reshet shva）——以色列的中央银行卡处理基础设施——并支持所有以色列发卡机构：Isracard、Visa Cal 和 Max（前身为 Leumi Card）。

本技能将指导你在以色列应用中集成 Tranzila，以接受信用卡付款（slikat kartis ashrai）。

官方文档： https://docs.tranzila.com/

测试凭据： 请向 Tranzila 支持团队索取适用于你终端的沙盒卡号，并通过 Tranzila 控制面板将终端配置为沙盒模式。博客文章和本技能旧版本中流传的测试卡信息并非供应商发布，不应视为有效信息。

说明

步骤 1：选择集成模式

根据用户的需求，帮助他们选择合适的方案：

模式	希伯来语	PCI 范围	最适合
Iframe	daf tashlum mutman	最小（通常为 SAQ A）	快速集成、最低合规负担
Hosted Fields	sdot mitarachim	较小（通常为 SAQ A-EP）	自定义结账体验，同时减轻 PCI 负担
API V2（服务器到服务器）	sharat le-sharat	最大（通常为 SAQ D）	令牌扣款、定期付款、退款

SAQ 的对应关系由 PCI 安全标准委员会制定，而非 Tranzila；是否符合资格取决于商户的整体环境以及收单机构的要求，因此应予以确认，不要假设它仅由集成方式决定。另请注意，PCI DSS v4 收紧了支付页面脚本要求（6.4.3 和 11.6.1），且 SAQ 表格已针对 v4.x 重新发布，因此请通过 PCI SSC 文档库查看当前的 SAQ A，不要再假设“用了 iframe 就什么都不用做”。

大多数以色列商户会先使用 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 ——随机 nonce（约 40 字节）
• X-tranzila-api-access-token ——hmac_sha256(secret + request_time + nonce, app_key)（以 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 的 Authentication 页面确认确切的拼接顺序。

提醒用户安全地存储凭据（例如使用环境变量或密钥管理器），绝不要将其提交到源代码管理中。

步骤 3：实现支付流程

选项 A：托管字段（推荐用于自定义用户体验）

托管字段让你可以设计自己的结账表单，同时由 Tranzila 安全地处理卡片信息：

1. 在页面中引入 Tranzila Hosted Fields JS
2. 为卡号、有效期和 CVV 创建容器 <div> 元素
3. 使用你的终端名称和样式选项初始化字段
4. 提交时，JS 会生成 TranzilaTK 令牌，卡片数据不会经过你的服务器
5. 将令牌发送到后端，通过 API V2 扣款

这样既能完全控制设计，又能满足 SAQ-A-EP PCI 合规要求。请参阅 https://docs.tranzila.com/ 下的 Hosted Fields 部分（深层路径经常变化，请从 Payments & Billing 索引导航）。

Webhook 签名验证。 当 Tranzila 将结果 POST 到你的通知页面（iframe 上的 notify_url_address，Bit API 上的 notify_url）时，切勿仅凭收到的数据格式就信任它。请使用供应商实际记录的机制进行验证：Hosted Fields 的 Response Hash 功能（使用你自己的密钥生成 response_hash，收到后可重新计算），或 Handshake API V2 流程；两者都在文档的 Payments and Billing 部分。也可以在表单字段中签入你自己的校验和，并在收到数据时验证。不要依赖 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： POST 到 https://secure5.tranzila.com/cgi-bin/tranzila71u.cgi，并传入 tranmode=C{index}（原交易的索引），以及 supplier、sum、currency、TranzilaTK、expdate、cred_type、TranzilaPW、CreditPass 和 authnr。CreditPass 是需要向 Tranzila 申请并在终端上启用的独立信用卡密码，因此从未进行过端到端测试的退款流程通常会首先在此处失败。
• API V2： POST https://api.tranzila.com/v1/transaction/credit_card/create，将 txn_type 设为 credit（返还资金）、cancel（取消扣款或退款）或 reversal（释放 J5 占用的信用额度），并通过 reference_txn_id 引用原交易。

编写代码前，请先确定使用的是哪种方式：两种方式的参数名称不能通用。

完整参数参考请参阅 references/api-parameters.md。

第 4 步：处理以色列特有的支付类型

以色列支付具有不同于国际支付处理的独特特征：

分期付款（Tashlumim）：

• 分期付款请设置 cred_type=8（cred_type=6 是发卡公司自己的信用计划，属于不同的产品）
• 参数：npay（付款次数减 1）、fpay（首期付款金额）、spay（后续每期付款金额）
• fpay + (npay * spay) 的总和必须等于总金额 sum
• 并非所有终端都获准支持分期付款（如果终端未启用此功能，你会收到错误；请在官方表格中核对具体代码）

信用类型（cred_type）：

值	类型	希伯来语
1	信用卡，常规单笔扣款	ashrai ragil
6	信用（kredit），发卡公司的信用计划	kredit
8	分期付款	tashlumim

当前 iframe 参数表仅公布这三个值（“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 接受 ISO 字母代码（ILS、USD、EUR、GBP 等），而不是数字型的 currency；分期计划使用 payment_plan 加上 installments_number、first_installment_amount 和 other_installments_amount，而不是 cred_type 加上 npay / fpay / spay；有效期使用整数类型的 expire_month 和 expire_year，而不是格式为 MMYY 的 expdate；持卡人 ID 使用 card_holder_id，而不是 myid。复制参数名称之前，请先确定你要集成的是哪种接口。

以色列身份证（teudat zehut）： 某些交易需要 myid 参数，即 9 位数的以色列身份证号码（mispar zehut）。应将其视为受监管的个人数据，而不是常规字段：根据《隐私保护法》及其第 13 号修正案，为支付目的收集的身份证号码与客户数据库中的其他数据一样，须履行相同义务。因此，不要将其记录在未加保护的应用程序日志中，不要超出收集目的所需期限保留，也不要将其放入分析数据负载中。

使用 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 令牌更长，因此切勿按长度验证令牌，也不要假设其末四位与卡号一致
   • 在数据库中存储令牌、到期日期和卡号末四位
   • 没有你的终端凭据，令牌毫无用处
   • 授权后切勿存储 CVV / CVV2，也绝不要存储完整卡号。 PCI DSS 要求 3.3.1 禁止在交易授权后保留敏感身份验证数据（CVV、完整磁条或芯片数据、PIN），即使经过加密也不允许。你只需保留令牌、到期日期和末四位。无论选择哪种集成模式，这一要求都适用；这是商户最常见的合规问题

3. 之后使用令牌扣款：

   • 使用 /cgi-bin/tranzila31tk.cgi 端点
   • 包含 TranzilaTK、expdate、sum 和 currency

步骤 6：添加 3D Secure（如有需要）

3D Secure V2 会添加持卡人身份验证。完整的基于重定向的流程请参阅 references/3ds-flow.md。要点：

• 3DS 会改变支付流程，加入银行身份验证步骤
• 响应中会包含身份验证状态的额外字段
• 部分以色列发卡机构可能不支持所有卡种的 3DS

步骤 7：接受 Bit 付款

Tranzila 通过专用 Bit API支持 Bit（以色列常用的移动支付应用），而不是通过信用卡扣款 CGI 的标记启用。该 API 在 https://api.tranzila.com/v1 下提供独立的 Bit - Init 和 Bit - Refund POST 端点，并采用与 API V2 其余接口相同的 4 个请求头 HMAC 身份验证方式。

1. 通过 API 调用 Bit Init 端点——Tranzila 会返回 Bit 付款 URL
2. 将客户重定向到 Bit URL，或显示二维码
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 规范，请从文档索引中的 Payments & Billing 部分导航至 https://docs.tranzila.com/（深层 Bit slug URL 会变动，也可能只是空白占位页）。

步骤 8：生成付款请求链接

付款请求（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 提供发票 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 月的发票早于该制度实施，因此从未需要分配编号。法规使用 עולה על（超过），所以金额恰好等于对应门槛的发票不在要求范围内。

根据法规原文，有两项限制值得纳入任何基于此规则构建的验证逻辑。仅涉及零税率或免税项目的发票不在要求范围内，因为第 47(א2)(1) 条仅适用于 לעניין חשבונית מס שהוצאה בשל עסקה שהמס שחל לגביה אינו בשיעור אפס，因此无论出口发票金额多大，都不需要分配编号。缺少编号的影响也有明确规定：第 38(א1) 条不允许买方抵扣进项 VAT：לא יותר ניכוי מס התשומות הכלול בחשבונית מס שסכומה, בלא המס, עולה על 5,000 שקלים חדשים (מינואר 2026 ועד מאי 2026: 10,000 שקלים חדשים) ושאינה כוללת מספר שהקצה לה המנהל。这并不会使发票作废，因此不要如此描述。请注意原文中的两点：它使用 עולה על（超过），所以金额恰好等于某一门槛的发票不在规则范围内；它也包含 2026 年 1 月至 5 月的门槛，因此可以直接依据法规确认这一安排，而不仅仅依赖供应商的摘要。此外，该条文没有要求买方提出申请：第 47(א2)(1) 条中的要求涉及卖方是否违反义务，而非买方是否可以抵扣，因此验证时绝不要把“没人要求”当作合规依据。如果通过 Tranzila 的发票 API 生成发票，请向 Tranzila 支持团队确认，超过当前门槛的发票是否会通过 SHAAM 提交分配编号申请；如果没有，请改用另一个确实接入 SHAAM 的发票服务商（Green Invoice、Morning 等），或直接通过 ITA 门户申请分配编号。

完整的发票 API 参考请参阅 Tranzila 的发票文档。

步骤 11：处理错误

检查每笔交易结果中的 Response 字段。000 表示已批准——其他代码均表示拒绝或错误。

重要：即使 API V2 调用对应的交易被拒绝或失败，HTTP 状态仍为 200。 HTTP 200 并不表示成功；请读取响应正文中的 Response／响应代码字段，查看实际的 SHVA 结果。此外，还有两个独立的代码体系：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	交易已批准	交易已完成
777	操作已完成；对于未记录交易的操作（包括 J2 和 J5），这是成功代码	对于仅验证的调用，将其视为成功
004	拒绝。请联系持卡人，向信用卡公司查询原因	请用户尝试使用另一张卡
006	身份证号码或 CVV 不正确	重新收集身份证号码／CVV
012	此终端未授权使用该卡	检查终端或品牌权限
015	卡已过期。请再次检查有效期	请用户更新卡片信息
016	未授权的货币	该终端尚未启用此货币
017	此交易使用了未授权的信用类型	该卡或终端的 cred_type 不正确
406	交易金额与首笔付款金额加上固定付款金额乘以付款次数的总和不符	重新计算分期金额
416	有效期无效	重新收集有效期
425	记录重复	使用幂等性机制，不要盲目重试
447	信用卡号不正确	重新收集卡号
900	交易在 3D Secure 身份验证阶段失败（3DS 代码组为 900-930，位于响应代码页面的另一个选项卡中）	重新进行身份验证，或在允许的情况下不使用 3DS 重试
905	3DS 代码组中的卡已过期（在 SHVA 代码组中，过期代码为 015）	请客户更新卡片
927 / 928	用户取消了卡片身份验证	客户退出了验证流程；这并非卡片故障

不要凭记忆将代码表用于你的集成。 对此技能进行的 2026 年审计发现，此处和随附脚本中先前列出的七个代码（033、036、037、039、091、125、200）在供应商的代码表中根本不存在；另外七个代码（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：接受一次性付款

用户说：“我需要在我的 Node.js 结账页面中添加信用卡付款” 操作：

1. 选择：Iframe 集成（将 PCI 范围降至最低）
2. 指导：嵌入 Iframe，填写供应商名称、金额和 currency=1（ILS）
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：处理分期付款

用户说：“我的客户想分 3 期支付 6,000 NIS” 操作：

1. 设置：cred_type=8（分期付款）
2. 计算：fpay=2000、spay=2000、npay=2（共 3 笔付款）
3. 验证：终端已获准处理分期付款
4. 处理：使用分期付款参数进行交易 结果：将付款拆分为 3 笔等额的 2,000 NIS 分期付款。

示例 4：退款

用户说：“我需要退还上周的一笔交易，确认码为 0283456” 操作：

1. 先选择接口。使用旧版 CGI 时，向 https://secure5.tranzila.com/cgi-bin/tranzila71u.cgi 发送 POST 请求；使用 API V2 时，向 /v1/transaction/credit_card/create 发送 POST 请求，并设置 txn_type=credit 和 reference_txn_id
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 发给客户（或显示二维码）
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 驱动位于 futureecom 供应商命名空间下，而不是 omnipay/tranzila（该名称在 Packagist 上会返回 404，这也是较早的指南会错误引用它的原因）。采用前请检查其发布日期。
• RubyGems 上有 active_merchant_tranzila（Ruby），但它唯一的版本是 2010 年 8 月发布的 0.0.1，而且 Tranzila 并非 ActiveMerchant 自带的支付网关。应将其视为已弃用；至多把它当作文档阅读，不要将其作为依赖项。

捆绑资源

参考资料

• references/api-parameters.md -- Tranzila API 参数完整参考，涵盖旧版 CGI 和 API V2 端点，包括身份验证标头、交易参数、令牌操作和分期付款字段。构造 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）。Agent 默认使用 JSON 请求正文，但 Tranzila 会拒绝或忽略这类请求。请以 application/x-www-form-urlencoded 格式发送请求。
• Tranzila 测试模式使用与生产环境相同的端点，但 supplier 参数不同。Agent 可能会误将测试交易发送到生产终端，或反过来。
• 旧版 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 的代码表中。若 Agent“认出”其中一个，就会自信地给商户错误诊断；最常见的是误称“信用卡已过期”，而实际问题通常出在终端向量或参数文件中。信用卡过期对应的代码是 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 要求的嵌入式银行卡信息采集，以及 Response Hash 回调完整性功能
交易响应代码	https://docs.tranzila.com/docs/payments-and-billing/transaction-response-codes	权威的 SHVA 和 3DS 代码表。请在此处按准确编号查询每个代码
身份验证（API V2 标头）	https://docs.tranzila.com/docs/payments-and-billing/authentication	四个 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。确认参数名称准确无误（区分大小写）。在官方 Transaction Response Codes 页面中查询准确的响应代码（参见 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”

原因：测试终端与生产终端的行为有所不同。 解决方案：确认生产终端名称和密码。某些操作（例如 void）在生产环境中的行为有所不同。如果行为存在差异，请咨询 Tranzila 支持。

错误：“Currency mismatch”

原因：货币使用了错误的端点。 解决方案：ILS 和 USD 使用 tranzila31.cgi。多币种（EUR、GBP 等）需要使用 tranzila36a.cgi。