VibeFox Pin Payments for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块不会安装在更旧的 PHP 版本上。
Pin Payments 账户：Pin Payments 商户账户（适用于澳大利亚或新西兰的企业；顾客可以在任何地方付款）。您需要其可公开密钥（publishable key）和私密密钥（secret key），分别用于正式环境，以及用于测试的测试环境。无需 Webhook 密钥：模块不使用 Webhook。银行卡信息由顾客的浏览器通过 Pin.js 直接发送至 Pin Payments，绝不会到达您的店铺，因此该店铺适用 PCI SAQ A-EP。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Pin Payments Gateway 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。
4. 在 Pin Payments 后台打开 Account > API Keys，将测试密钥复制到 Test publishable key 和 Test secret key 中。保持 Test mode 开启，打开 Enable/Disable，然后点击 Save。
5. 使用 Pin Payments 测试卡下一笔测试订单。一切正常后，输入正式密钥，关闭 Test mode 并保存。
安装时，模块会创建订单状态 Pin Payments payment on hold。PrestaShop 会为安装时已启用的币种、顾客群组和国家提供新的付款模块。您可以在 Payment > Preferences 中更改此设置；之后启用的国家必须在那里勾选。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Pin Payments Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，页面会在测试模式开启时显示警告，在当前模式的可公开密钥或私密密钥为空时显示错误，并在 Pin Payments 不支持店铺默认币种时显示错误（附带支持的币种列表）。如果缺少当前模式的两个密钥，付款方式在结账时会被隐藏。Title 为空时无法保存：页面会显示 Enter a title for the payment method.
Pin Payments
Enable/Disable：Enable Pin Payments 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Credit card (Pin Payments)。必填。
Description：结账时显示在付款方式下方的文字。默认：Pay with your credit card via Pin Payments。
API 密钥
您可以在 Pin Payments 后台的 Account > API Keys 中找到密钥。测试密钥仅适用于测试 API，正式密钥仅适用于正式 API。可公开密钥由顾客浏览器中的 Pin.js 使用。私密密钥绝不会离开您的服务器。
Test mode：使用 Pin Payments 测试环境（test-api.pinpayments.com）和测试密钥。不会产生真实扣款，顾客会在付款方式下方看到 TEST MODE — no real charges will be made. 关闭时，使用正式 API 和正式密钥。默认：开启。
Test publishable key：您的 Pin Payments 测试账户的可公开密钥。
Test secret key：您的 Pin Payments 测试账户的私密密钥。
Live publishable key：您的 Pin Payments 正式账户的可公开密钥。
Live secret key：您的 Pin Payments 正式账户的私密密钥。
密钥前后的空格会被去除。已保存的私密密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Clear saved secrets：勾选某个私密密钥并点击 Save 即可将其删除。字段为空时保留已保存的值。
高级
Debug log：写入模块文件夹中的 logs/wc_ppg_debug.log.php。该文件无法通过网页打开。错误始终会被记录；开启此选项可同时记录每次 API 调用。银行卡数据、API 密钥和顾客个人数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载模块会删除网关设置和日志。订单的付款数据（扣款和退款）以及订单状态 Pin Payments payment on hold 始终保留。默认：关闭。
结账
当该付款方式已启用、当前模式的两个密钥均已设置、购物车币种是 14 种受支持币种之一（AUD、USD、NZD、SGD、EUR、GBP、CAD、HKD、JPY、MYR、THB、PHP、ZAR、IDR），且 Payment > Preferences 中允许该模块用于此购物车时，会显示该付款方式。
在付款步骤，顾客选择付款方式（默认为 Credit card (Pin Payments)，并显示 Visa、Mastercard 和 American Express 图标），然后填写 Card number、Expiry (MM / YY)、CVC 和 Name on card。提交前，表单会检查银行卡号长度、有效期月份和年份、3 或 4 位的 CVC 以及姓名。
顾客下单时，Pin.js 会将银行卡信息和购物车的账单地址从浏览器直接发送至 Pin Payments，并获得一次性银行卡令牌。只有该令牌会发送至您的店铺。随后，模块会以购物车币种为购物车总额创建一笔已捕获的扣款，附带顾客的电子邮件和描述 <shop name> - Cart <cart number>。Pin Payments 在同一请求中响应。在收到此响应之前，不会存在任何订单。
扣款成功后，订单被创建，顾客会看到标准的订单确认页面，显示 Your card payment has been received. 如果订单进入了 Pin Payments payment on hold，页面会显示 Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.
如果 Pin Payments 没有响应（超时、服务器错误、响应无法读取），扣款仍可能已经生成。此时订单会在未付款的情况下以 Pin Payments payment on hold 创建，确认页面会显示 We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. 重新提交同一购物车绝不会产生第二笔扣款。
同一购物车同一时间只会进行一次付款尝试。第二次提交会收到 This order is already being paid. Please wait a moment and check your e-mail before trying again. 已有订单的购物车，或者之前已扣款或可能已扣款的尝试，不会再次扣款；订单会根据该次尝试创建。银行卡令牌只能使用一次：付款失败后，或顾客更改银行卡信息时，都会生成新的令牌。
付款失败时，不会创建订单。顾客停留在付款步骤，购物车保留，并显示以下提示之一：Your card was declined. Please use another card or contact your bank.；Your card has insufficient funds. Please use another card.；Your card has expired. Please use another card.；The card security code (CVC) is incorrect.；This card type is not accepted. Please use Visa, Mastercard or American Express.；Payment failed: 附带 Pin Payments 对被拒信息给出的原因；Your card details have expired. Please enter them again and retry.，当令牌无法使用时；The secure card form could not be loaded. Please reload the page or choose another payment method.，当 Pin.js 未能加载时；Card payments are temporarily unavailable. Please try again later or choose another payment method.，当 Pin Payments 拒绝私密密钥时；Your payment could not be processed. Please try again or choose another payment method.，用于其他错误。技术原因会写入日志。
模块没有 3-D Secure 流程。如果您的 Pin Payments 账户要求 3-D Secure，扣款将保持待定，不会创建订单，顾客会看到 Your card payment could not be completed (additional verification is required). Please try another card or another payment method. 不存在带后续扣款的仅授权模式、保存银行卡、订阅、Apple Pay 或 Google Pay，也没有 Webhook。
订单与退款
订单状态
No order yet：银行卡被拒、扣款需要 3-D Secure，或顾客尚未付款。仅存在购物车。
Payment accepted：Pin Payments 报告了与购物车金额和币种完全一致的成功且已捕获的扣款。付款以 Pin Payments 扣款令牌作为交易 ID 记录，备注会显示金额和扣款令牌（测试付款还会显示 TEST MODE）。
Pin Payments payment on hold：扣款需要您审核。备注会说明原因：Pin Payments 扣除的金额或币种与购物车不同（会记录已扣金额的付款），付款期间购物车发生了变化，扣款已授权但未捕获（请在 Pin Payments 后台捕获，然后将订单设置为已接受付款），或 Pin Payments 没有给出明确的响应（不会记录付款；发货前请在 Pin Payments 后台查找扣款描述）。
Refunded：扣款已通过模块全额退款。
如果对已有订单的购物车再次扣款，订单不会改变。备注会要求您检查并在 Pin Payments 后台退款。
Pin Payments 区块
订单页面会显示一个 Pin Payments 区块，其中包括测试付款的 Test mode 标识、扣款令牌、状态、银行卡品牌和末四位、已扣金额、订单总额和已退金额、Description at Pin Payments、退款历史，以及订单的 Pin Payments notes。
退款
在 Pin Payments 区块中输入金额（尚未退款的金额会自动填入），可选填写原因，然后点击 Refund via Pin Payments。确认提问 Refund this amount through Pin Payments? This cannot be undone. 支持全额和部分退款。您需要具有编辑订单的权限。退款金额和币种仅限于 Pin Payments 实际扣除的金额和币种，因此在金额或币种不一致之后，您可以退款的上限是顾客实际支付的金额，而不是订单总额。退款会发送至订单付款时所用的环境（测试或正式），因此该模式的私密密钥必须已设置。Pin Payments 异步处理退款，因此状态通常为待处理。成功的请求会与 Pin Payments 退款令牌及其状态一起添加到退款历史和备注中。全额退款会将订单设置为 Refunded。部分退款不会改变状态。如果 Pin Payments 拒绝退款或没有响应，区块会显示错误，且不会记录退款。
如果订单没有记录的扣款（Pin Payments 没有给出明确的响应），区块不会显示退款表单，并会告诉您应在 Pin Payments 后台查找哪条描述。
模块不会生成退款单（credit slip）。订单页面中标准的 PrestaShop 退款按钮不会通过 Pin Payments 退款。在 Pin Payments 后台所做的退款不会同步回 PrestaShop，因此请在订单页面进行退款。
许可证密钥
模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Pin Payments Gateway 位于 Modules > Module Manager > VibeFox Pin Payments Gateway > Configure 页面的最顶部，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以掩码方式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除该密钥）。其下方是 Product: presta-payment-pinpayments 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。在店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后已知的状态运行。
一个密钥仅适用于一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Pin Payments。即使如此仍发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡上会出现提醒。现有订单不受影响：对之前已付款订单的退款仍可正常进行。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。您在后台工作时，系统会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Pin Payments：请检查许可证是否有效，Enable/Disable 是否开启，当前模式的两个密钥是否都已填写（测试模式下为 Test publishable key 和 Test secret key，否则为正式密钥），以及购物车币种是否为 14 种受支持币种之一。在 Payment > Preferences 中，检查模块是否允许用于购物车币种、顾客所在国家和顾客群组。设置页面会在密钥缺失以及店铺币种不受支持时显示错误。
付款已完成，但订单为 Pin Payments payment on hold：请阅读 Pin Payments 区块中的备注（参见订单状态）。如果 Pin Payments 没有给出明确的响应，请在 Pin Payments 后台查找描述为 <shop name> - Cart <cart number> 的扣款，然后发货或在后台退还该笔扣款。
顾客看到 Your payment was received, but the order could not be completed automatically：银行卡已扣款，但 PrestaShop 无法创建订单（例如，模块在此期间被禁用）。原因记录在日志中。系统会请顾客不要再次付款；重新提交同一购物车会在不产生新扣款的情况下创建订单。
顾客看到 Card payments are temporarily unavailable：Pin Payments 拒绝了私密密钥，或当前模式的密钥缺失。测试密钥仅适用于测试模式，正式密钥仅适用于正式模式。日志会显示原因。
订单因 additional verification is required 而失败：您的 Pin Payments 账户要求 3-D Secure，而模块不支持该功能。请要求 Pin Payments 关闭强制性的 3-D Secure。
无法加载安全银行卡表单：Pin Payments CDN 的 Pin.js 没有在浏览器中加载，例如因为脚本拦截器，或因为某个模块合并或更改了脚本。请将结账页面排除在此类优化之外。
Pin Payments 没有响应：在浏览器中 30 秒内未创建银行卡令牌。顾客可以检查网络连接后重试；没有任何扣款。
付款因 Pin Payments 原因失败：Pin Payments 拒绝了扣款信息，例如金额低于该币种的最低扣款额。顾客会看到原因，日志中会有错误代码。
退款失败：请阅读区块中的提示。关于 TEST 或 LIVE 模式的提示表示，付款所用模式的私密密钥为空。Pin Payments did not confirm the refund 表示没有收到响应；请在重试前检查 Pin Payments 后台的扣款。at most 显示该扣款仍可退还的金额。
测试付款：测试模式使用测试环境和测试密钥。请使用 Pin Payments 开发者文档中的测试卡，例如 4200 0000 0000 0000（成功）或 4100 0000 0000 0001（被拒），有效期可任意填写未来日期，CVC 任意填写。订单会保留其付款时所用的模式，因此切换模式后，退款仍会发送到正确的环境。
错误信息在哪里查看：错误始终会写入日志；请参见模块页面上的 Log 字段。开启 Debug log 可查看每次 API 调用。
卸载
进入 Modules > Module Manager，打开 VibeFox Pin Payments Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置和日志将被删除。如果已关闭，所有设置都会保留，以便之后重新安装。Pin Payments 的扣款和退款以及订单状态 Pin Payments payment on hold 始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Pin Payments 是其各自所有者的商标。本模块与 Pin Payments 无关联，也未获得 Pin Payments 的认可。