VibeFox Pin Payments for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Pin Payments 账户：Pin Payments 商户账户（适用于澳大利亚或新西兰的企业；顾客可以从任何地方付款）。您需要其 publishable key 和 secret key：正式环境用一组，测试时则用测试环境的一组。不需要 webhook secret：本扩展不使用 webhook。银行卡信息由顾客的浏览器通过 Pin.js 直接发送到 Pin Payments，绝不会到达您的店铺，因此店铺适用 PCI SAQ A-EP 标准。
货币：AUD、USD、NZD、SGD、EUR、GBP、CAD、HKD、JPY、MYR、THB、PHP、ZAR 或 IDR。订单以其自身货币扣款。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，包含两个 OpenCart 版本的安装包。请在您的电脑上解压。压缩包包含 README.txt、OpenCart 3 安装包 wcp_pinpayments_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_pinpayments_gateway.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_pinpayments_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录中。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Pin Payments Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要拥有修改付款扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key，然后点击 Activate（参见 License key）。
4. 在 Pin Payments 后台打开 Account > API Keys，将测试密钥复制到 Test publishable key 和 Test secret key。保持 Test mode 开启，开启 Enable/Disable，然后点击 Save。
5. 使用 Pin Payments 测试卡进行一次测试下单。一切正常后，输入正式环境密钥，关闭 Test mode 并保存。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_pinpayments_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法工作。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Pin Payments Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 3 至第 5 步输入许可证密钥和 Pin Payments 密钥。两个版本的设置页面及其字段相同。
新安装默认关闭付款方式，并开启测试模式。
配置
所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Pin Payments Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在开启测试模式时，设置上方页面会显示 Pin Payments 处于测试模式：使用测试 API 和测试密钥，不会产生真实扣款。；当前模式的 publishable key 或 secret key 为空时会显示错误（此时结账页面会隐藏该付款方式）；当 Pin Payments 不支持店铺的默认货币时也会显示错误（并列出支持的货币）。如果没有修改扩展的权限，页面会显示设置但无法保存。
保存时，如果某个字段有误，则不会保存任何内容：Title 不能为空（请输入付款方式的标题（最多 128 个字符）。），Sort Order 必须为整数（允许负数），Total 必须为 0 或更大的数字，Geo Zone 和订单状态必须存在。
Pin Payments
Enable/Disable：Enable Pin Payments 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Credit card (Pin Payments)。必填，最多 128 个字符。
Description：顾客在 Confirm Order 步骤中、银行卡表单上方看到的文字。默认：Pay with your credit card via Pin Payments.
Sort Order：Pin Payments 在结账时付款方式中的位置。留空或输入整数。
Geo Zone：仅对所选地理区域内的付款地址显示银行卡表单。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total：订单必须达到的购物车金额（以店铺默认货币计算），达到后才会提供该付款方式。留空则对任何金额都提供。
API 密钥
您可以在 Pin Payments 后台（该页面链接到 dashboard.pinpayments.com）的 Account > API Keys 下找到密钥。测试密钥仅适用于测试 API，正式密钥仅适用于正式 API。Publishable key 由顾客浏览器中的 Pin.js 使用。Secret key 绝不会离开您的服务器。
Test mode：使用 Pin Payments 测试环境（test-api.pinpayments.com）和测试密钥。不会产生真实扣款，顾客会在银行卡表单上方看到 测试模式 — 不会产生真实扣款。 关闭时，使用正式 API 和正式密钥。订单的退款始终使用该订单付款时所在环境的密钥。默认：开启。
Test publishable key：您的 Pin Payments 测试账户的 publishable key。
Test secret key：您的 Pin Payments 测试账户的 secret key。
Live publishable key：您的 Pin Payments 正式账户的 publishable key。
Live secret key：您的 Pin Payments 正式账户的 secret key。
密钥前后的空格会被去除。已保存的 secret key 不会再次显示。字段保持为空，并显示 已保存 — 留空即可保持不变。 只有在需要更改时才输入新值。要删除已保存的 secret key，请勾选字段下方的 Clear the saved value on save，然后点击 Save。
订单
OpenCart 在 Confirm Order 步骤创建订单时不设状态（缺失订单）。只有在 Pin Payments 对扣款作出答复之后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。
Order Status After Payment：银行卡已按订单的金额和货币精确扣款。默认：Processing。
On Hold (Review) Status：扣款的金额或货币与订单不符，扣款已授权但未捕获，或 Pin Payments 未给出明确答复（超时、服务器错误），因此可能已存在扣款。备注会告诉您需要在 Pin Payments 后台核对什么。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。
Refunded Status：通过订单标签页将付款全额退款后设置。默认：Refunded。
高级
Debug log：将 Pin Payments API 调用写入 OpenCart 日志文件夹（storage/logs）中的 wc_ppg_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移动到 wc_ppg_debug.old.log.php。错误和警告始终会被记录；开启此选项可额外记录每一次 API 调用。银行卡数据、API 密钥和顾客个人数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启后，卸载扩展时会删除网关设置和日志。订单的付款数据（扣款和退款）始终保留。默认：关闭。
导入 / 导出
Export：Download JSON 会将设置保存为 JSON 文件。Secret key 不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 secret key 会被保留。
结账
当该付款方式已开启、当前模式的两个密钥均已填写、订单货币属于 14 种受支持货币之一、付款地址位于所选 Geo Zone 内、且订单达到 Total 时，才会显示该付款方式。
在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit card (Pin Payments)）。OpenCart 在 Confirm Order 步骤创建订单，此时仍无状态。顾客在此处会看到您的描述、Visa、Mastercard 和 American Express 图标，以及银行卡表单：Card number、Expiry (MM / YY)、CVC 和 Name on card。在 OpenCart 4 上，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式；银行卡表单随后出现在结账页面底部的确认区块中，位于 Confirm Order 按钮上方。提交前，表单会检查卡号长度、有效期月份和年份、3 位或 4 位的 CVC 以及持卡人姓名。
顾客点击 Confirm Order 后，Pin.js 会从浏览器直接将银行卡信息和订单的付款地址（在 OpenCart 4 上，如果结账不要求付款地址，则使用配送地址）发送至 Pin Payments，并获得一个一次性卡令牌。只有该令牌会被发送到您的店铺。随后，扩展会以订单货币为订单总额创建一笔已捕获的扣款，附带顾客的电子邮件和 IP 地址，描述为 <store name> - Order <order number>。Pin Payments 在同一请求中作出答复。
扣款成功后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存；购物车会被清空，顾客会看到 OpenCart 的订单成功页面，并显示 Your card payment has been received. 如果订单进入了审核状态，页面会显示 您的银行卡付款已收到，正在审核中。审核完成后，我们会更新您的订单。
如果 Pin Payments 没有响应（超时、服务器错误、无法读取的响应），则扣款可能已经创建。此时订单会被置为审核状态并附带备注，成功页面会显示 我们无法通过 Pin Payments 确认您的付款。再次付款前，请检查您的电子邮件和银行卡账单，或与我们联系。 重新提交同一购物车绝不会产生第二笔扣款。
每个购物车同一时间只会运行一次付款尝试。第二次提交会收到 此订单正在付款中。请稍候，并在再次尝试前查看您的电子邮件。 OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，OpenCart 4 则会更新结账中的订单（在付款被拒绝后，顾客会支付同一订单），因此已被其他订单付款的购物车会直接进入成功页面；而之前已经扣款或可能已经扣款的尝试，会将其状态转给该订单，而不会创建新的扣款。一个卡令牌只能使用一次：在失败的尝试之后，或顾客更改银行卡信息时，都会创建新的令牌。
OpenCart 4 会在结账页面保留订单，直到显示成功页面。如果该订单在顾客确认新购买时已经有了状态（例如它已付款但从未打开成功页面，或您已将其取消），顾客会被带回结账页面，下一次 Confirm Order 将为当前购物车付款一个新订单。在结账页面上方，订单已关闭时顾客会看到 商店已取消或退款了您之前的订单。请重新确认订单，以新订单付款。；若订单是为较早的购物车创建的，则会看到 您之前的订单 #(number) 已下单。您的购物车已更改：请确认新订单以支付。 已付款的订单绝不会在另一个购物车下显示为已付款。
付款失败时，订单仍无状态。顾客停留在 Confirm Order 步骤，购物车会被保留，银行卡表单上方会显示以下消息之一：您的银行卡被拒绝。请使用其他银行卡或联系您的银行。；您的银行卡余额不足。请使用其他银行卡。；您的银行卡已过期。请使用其他银行卡。；银行卡安全码（CVC）不正确。；不接受此类银行卡。请使用 Visa、Mastercard 或 American Express。；付款失败：附上 Pin Payments 对被拒绝信息给出的原因；您的银行卡信息已过期。请重新输入后再试。（令牌无法使用时）；无法加载安全银行卡表单。请刷新页面或选择其他付款方式。（Pin.js 未加载时）；银行卡付款暂时不可用。请稍后再试或选择其他付款方式。（Pin Payments 拒绝 secret key 时）；无法处理您的付款。请重试或选择其他付款方式。（其他错误）。技术原因会写入日志。
本扩展没有 3-D Secure 流程。如果您的 Pin Payments 账户要求 3-D Secure，扣款会保持待处理，订单不会获得状态，顾客会看到 无法完成您的银行卡付款（需要额外验证）。请尝试其他银行卡或其他付款方式。 本扩展没有仅授权、之后再捕获的模式，也不支持保存银行卡、订阅、Apple Pay 或 Google Pay，以及 webhook。
订单与退款
订单状态
无状态（缺失订单）：银行卡被拒绝、扣款需要 3-D Secure，或顾客尚未付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。
Order Status After Payment（默认 Processing）：Pin Payments 报告了一笔成功且已捕获的扣款，金额和货币与订单完全一致。备注会显示金额和扣款令牌（测试付款还会显示 TEST MODE）。
On Hold (Review) Status（默认 Pending）：扣款需要您进行审核。备注会说明原因：Pin Payments 扣除的金额或货币与订单不同；扣款已授权但未捕获（请在 Pin Payments 后台捕获，然后更改订单状态）；或 Pin Payments 未给出明确答复（在发货之前，请在 Pin Payments 后台查找扣款描述）。
Refunded Status（默认 Refunded）：扣款已通过该扩展全额退款。
如果对已付款的购物车又产生了第二笔扣款，已付款的订单不会改变。备注会要求您检查该笔扣款，并在 Pin Payments 后台退款。
备注是订单 History 中的条目，顾客看不到。
VibeFox Pin Payments Gateway tab
在 Sales > Orders 中打开一个通过 Pin Payments 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的 VibeFox Pin Payments Gateway 标签页会显示 Charge 令牌（测试付款带有 Test 标签）、Status、Card 品牌及后四位数字、Charged / order / refunded（已扣款 / 订单 / 已退款）金额、Charge description、退款表单、退款历史以及订单的 Pin Payments notes。该标签页仅对有权访问该扩展的用户显示。
退款
在 VibeFox Pin Payments Gateway 标签页中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Pin Payments。请确认提示 是否通过 Pin Payments 退还此金额？此操作无法撤销。 支持全额和部分退款。您需要拥有修改该扩展的权限（在 System > Users > User Groups 中设置）。退款金额和货币以 Pin Payments 实际扣款的为准，因此在金额或货币不一致之后，您最多可以退还顾客实际支付的金额，而不是订单总额。退款会发送到订单付款时所在的环境（测试或正式），因此该模式的 secret key 必须已设置。Pin Payments 异步处理退款，因此状态通常为 Pending。成功的请求会与 Pin Payments 退款令牌及其状态一起添加到退款历史和备注中。全额退款会将订单设为 Refunded Status，且不会通知顾客，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。如果 Pin Payments 拒绝退款或没有响应，标签页会显示错误，且不会记录任何退款。
如果订单没有任何扣款记录（Pin Payments 未给出明确答复），标签页不会显示退款表单，而是会告诉您应在 Pin Payments 后台查找哪个描述。
Sales > Returns 中的商品退货不会通过 Pin Payments 退还款项。在 Pin Payments 后台完成的退款不会同步回 OpenCart，因此请在订单页面中办理退款。
许可证密钥
本扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Pin Payments Gateway 位于 Extensions > Extensions > Payments > VibeFox Pin Payments Gateway > Edit 的设置上方，是第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除该密钥）。其下方是 Product: opencart-payment-pinpayments 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随管理后台语言（包括英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。在店铺地址变更后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后一次已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效的密钥，顾客在结账时将看不到 Pin Payments。如果仍然发起了付款，顾客会看到 此付款方式不可用。请选择其他方式。 在同一浏览器中登录后台的管理员用户仍可在店铺中看到该付款方式，并标有 (无许可证 — 仅管理员可见)，因此您可以在购买密钥之前进行设置和测试。在 OpenCart 4 上没有此预览：商店看不到管理员登录状态，因此没有有效密钥时，付款方式对所有人都会隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：之前付款的退款仍可正常进行。
许可证过期后，扩展仍会继续工作，但更新和支持需要续期。打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，许可证密钥和许可证状态总会被删除。
故障排除
结账时不显示 Pin Payments：请检查许可证是否有效、Enable/Disable 是否开启、当前模式的两个密钥是否已填写（测试模式为 Test publishable key 和 Test secret key，否则为正式密钥），以及订单货币是否属于 14 种受支持货币之一。另外请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。如果缺少密钥或店铺货币不受支持，设置页面会显示错误。
付款已完成，但订单处于审核状态：请阅读 VibeFox Pin Payments Gateway 标签页中的备注（参见订单状态）。如果 Pin Payments 没有给出明确答复，请在 Pin Payments 后台查找描述为 <store name> - Order <order number> 的扣款，然后处理订单或在后台退还该扣款。
顾客看到「Your payment was received, but the order could not be completed automatically」：银行卡已扣款，但无法设置订单状态（例如订单在此期间被删除）。原因记录在日志中。系统会请顾客不要再次付款；重新提交同一购物车可以在不产生新扣款的情况下为订单设置状态。
顾客看到「This payment method is not available. Please reload the checkout page.」：结账会话已与订单不再匹配，或该付款方式已在此期间被关闭。顾客需要重新加载结账页面。
顾客看到「Card payments are temporarily unavailable」：Pin Payments 拒绝了 secret key，或当前模式的密钥缺失。测试密钥仅适用于测试模式，正式密钥仅适用于正式模式。日志会显示原因。
订单因「additional verification is required」而失败：您的 Pin Payments 账户要求 3-D Secure，而本扩展不支持该功能。请要求 Pin Payments 关闭强制 3-D Secure。
无法加载安全银行卡表单：Pin.js 未能在浏览器中从 Pin Payments CDN 加载，例如因为脚本拦截器，或某个合并或修改脚本的扩展。请将结账页面排除在此类优化之外。
Pin Payments 没有响应：浏览器未能在 30 秒内创建银行卡令牌。顾客可以检查网络连接后重试；未发生任何扣款。
付款因 Pin Payments 的原因失败：Pin Payments 拒绝了扣款信息，例如金额低于该货币的最低扣款金额。顾客会看到原因，日志中则包含错误代码。
退款失败：请阅读标签页中的消息。与 TEST 或 LIVE 模式相关的消息表示订单付款所在模式的 secret key 为空。Pin Payments did not confirm the refund 表示没有收到答复；请在重试之前在 Pin Payments 后台检查该扣款。at most 表示该扣款仍可退还的金额。
测试付款：测试模式使用测试环境和测试密钥。请使用 Pin Payments 开发者文档中的测试卡，例如 4200 0000 0000 0000（成功），有效期使用任意未来日期，CVC 任意填写。订单会保留其付款时所在的模式，因此即使切换了模式，退款仍会进入正确的环境。
在哪里查找错误：错误始终会写入日志；请查看扩展页面上的 Log 字段。开启 Debug log 可查看每一次 API 调用。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Pin Payments Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 订单部分中的订单状态，重新安装时它们会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 上，还会删除其两个事件，它们分别在成功页面和结账页面上方显示消息）。如果 Delete data on uninstall 已开启，其他网关设置（标题、描述、测试模式、密钥、调试日志开关）和日志也会被删除；如果关闭，它们会被保留，供以后重新安装时使用。Pin Payments 的扣款和退款记录总会被保留，因此之前付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 上，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Pin Payments Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Pin Payments 是其各自所有者的商标。本扩展与 Pin Payments 无关联，也未获得 Pin Payments 的认可。