VibeFox Pin Payments for WooCommerce — 帮助
系统要求
WordPress：6.2 或更高版本。
WooCommerce：7.1 或更高版本，已安装并启用。没有 WooCommerce 时，插件无法激活。
PHP：8.0 或更高版本。
HTTPS：您的结账页面必须使用 HTTPS，这是接受银行卡付款所要求的（PCI DSS）。银行卡信息通过 Pin.js 从顾客的浏览器直接发送至 Pin Payments，绝不会到达您的服务器，因此该店铺适用 PCI SAQ A-EP。
Pin Payments 账户：Pin Payments 商户账户（适用于澳大利亚或新西兰的企业；顾客可以在任何地方付款）。您需要其可公开的密钥（publishable key）和私密密钥（secret key）：正式环境使用正式密钥，测试则使用测试环境的密钥。不需要 Webhook 密钥：本插件不使用 Webhook。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_pinpayments_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Pin Payments > Manage，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 在 Pin Payments 后台打开 Account > API Keys，将测试密钥复制到 Test publishable key 和 Test secret key。保持 Test mode 开启，启用 Enable/Disable 并保存。
6. 使用 Pin Payments 测试卡下测试订单。一切正常后，输入正式密钥，关闭 Test mode 并保存。
配置
所有设置都在同一页面：WooCommerce > Settings > Payments > Pin Payments。在字段上方，页面会在测试模式开启时显示提示，在当前模式的可公开密钥或私密密钥为空时显示错误，并在 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：Enable test mode。使用 Pin Payments 测试环境（test-api.pinpayments.com）和测试密钥。不会产生实际扣款，顾客在银行卡表单中会看到 测试模式 — 不会产生任何实际扣款。。关闭时，使用正式 API（api.pinpayments.com）和正式密钥。默认：开启。
Test publishable key：您的 Pin Payments 测试账户的可公开密钥。
Test secret key：您的 Pin Payments 测试账户的私密密钥。这是一个密码字段。
Live publishable key：您的 Pin Payments 正式账户的可公开密钥。
Live secret key：您的 Pin Payments 正式账户的私密密钥。这是一个密码字段。
密钥前后的空格会被删除。当前模式的两个密钥都必须填写，否则结账时不会显示该网关。
高级
Debug log：Log Pin Payments API calls — 日志保存在 WooCommerce > Status > Logs 中，来源为 wcp_pinpayments_gateway。错误始终会被记录；开启此选项可额外记录每一次 API 调用。银行卡数据、API 密钥和顾客个人数据绝不会被记录。默认：关闭。
Delete data on uninstall：Delete the gateway settings and logs when the plugin is deleted。停用插件绝不会删除任何内容。订单中保存的付款数据始终会保留。默认：关闭。
结账
顾客选择付款方式（默认为 Credit card (Pin Payments)，并显示 Visa、Mastercard 和 American Express 图标），然后在您的结账页面填写 Card number、Expiry (MM / YY)、CVC 和 Name on card。提交前，银行卡表单会检查卡号长度、有效期月份和年份、3 或 4 位 CVC 以及持卡人姓名。
下单时，Pin.js 会从浏览器直接将银行卡信息和账单地址发送至 Pin Payments，并获得一次性银行卡令牌。只有该令牌会被发送到您的服务器。随后，您的服务器会以订单币种创建一笔已捕获的扣款，金额为订单总额，描述为 <store name> - Order <number>。Pin Payments 会在同一请求中作出响应。只有在 Pin Payments 报告扣款成功，并且扣款金额和币种与订单完全一致时，订单才会标记为已付款。之后，顾客会被带到订单接收页面。
每个订单同一时间只会处理一次付款尝试。第二次提交会收到 该订单正在付款中。请稍候片刻，并在重试前查看您的电子邮件。 已付款的订单，或已扣款并被保留的订单，绝不会再次扣款。银行卡令牌只能使用一次：付款失败后，或顾客更改银行卡信息后，会生成新的令牌。
顾客可能看到的消息：您的银行卡被拒绝。请使用其他银行卡或联系您的银行。；您的银行卡余额不足。请使用其他银行卡。；您的银行卡已过期。请使用其他银行卡。；银行卡安全码（CVC）不正确。；不接受此类银行卡。请使用 Visa、Mastercard 或 American Express。；付款失败：附带 Pin Payments 对被拒信息给出的原因；您的银行卡信息已过期。请重新输入后再试。（令牌无法使用时）；无法加载安全银行卡表单。请刷新页面或选择其他付款方式。（Pin.js 无法加载时）；银行卡付款暂时不可用。请稍后再试或选择其他付款方式。（Pin Payments 拒绝私密密钥时）；我们无法通过 Pin Payments 确认您的付款。请在重试前检查您的电子邮件和银行卡账单，或与我们联系。（Pin Payments 无响应时）。技术详情会记录在订单备注和日志中。
该付款方式适用于经典结账、结账区块（字段相同）以及 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。
插件不支持 3-D Secure 流程。如果您的 Pin Payments 账户要求 3-D Secure，扣款会保持待定，插件会使订单失败，因此该次尝试不会扣除任何款项；顾客会看到 您的银行卡付款无法完成（需要额外验证）。请尝试其他银行卡或其他付款方式。 不提供仅授权后续捕获模式，不支持保存银行卡、WooCommerce 订阅、Apple Pay 或 Google Pay，也不支持 Webhook。
订单与退款
Order statuses
Processing：Pin Payments 报告了与订单金额和币种完全一致的成功、已捕获扣款。仅包含虚拟可下载商品的订单会变为已完成，即 WooCommerce 默认行为。订单备注会显示金额和扣款令牌（测试付款还会显示 TEST MODE）。交易 ID 即为 Pin Payments 扣款令牌。
Failed：银行卡被拒绝，扣款保持待定（3-D Secure），Pin Payments 拒绝了私密密钥或请求。每次失败的尝试都会在订单中添加一条备注，包含 Pin Payments 错误代码和消息，即使订单因之前的尝试已处于失败状态也是如此。顾客可以用同一订单重新尝试。
Pending payment：Pin Payments 未给出明确答复（超时、服务器错误、无法解析的响应）。订单不会被标记为失败，因为扣款可能仍已生成。备注会提示您在顾客再次付款或订单发货之前，先在 Pin Payments 后台查找该扣款的描述。该状态为待付款。
On hold：Pin Payments 扣款的金额或币种与订单不一致（备注会显示预期金额和实际扣款金额），或扣款已授权但未捕获。在履行订单之前，请先在 Pin Payments 后台检查该扣款。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Credit card (Pin Payments)（按钮会显示您的 Title）。支持全额和部分退款。退款会发送至订单付款时所在的环境（测试或正式），因此该模式的私密密钥必须已设置。请求成功后，订单会添加一条备注，包含金额、Pin Payments 退款令牌及其状态。Pin Payments 异步处理退款，因此状态通常为 Pending。如果 Pin Payments 拒绝退款或未响应，WooCommerce 会显示错误，且不会记录退款。
在 Pin Payments 后台所做的退款不会同步回 WooCommerce，因此请通过 WooCommerce 进行退款。
许可证密钥
插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Pin Payments 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至哪一天以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，Pin Payments 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 该付款方式不可用。请选择其他付款方式。 已登录的店铺管理员仍会看到该付款方式，并标注为 （未授权 — 仅管理员可见），以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：退款仍可正常进行。
许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 Pin Payments：请检查许可证是否有效，Enable/Disable 是否已开启，当前模式的两个密钥是否都已填写（测试模式下为 Test publishable key 和 Test secret key，否则为正式密钥），以及购物车币种是否为 14 种支持币种之一。在 Pay for order 页面，以订单币种为准。设置页面会对缺失密钥和不支持的币种显示错误。
结账页面显示「我们无法确认您的付款」：Pin Payments 未能及时响应。订单会保持待付款状态并附带备注。在顾客再次付款或订单发货之前，请在 Pin Payments 后台查找描述为 <store name> - Order <number> 的扣款。插件不会自动查找此类扣款，新的尝试会创建新的扣款。
顾客看到「银行卡付款暂时不可用」：Pin Payments 拒绝了私密密钥。订单备注会提示检查当前模式的密钥。测试密钥仅适用于测试模式，正式密钥仅适用于正式模式。
订单失败并显示「需要额外验证」：您的 Pin Payments 账户要求 3-D Secure，而插件不支持该功能。请要求 Pin Payments 关闭强制 3-D Secure。
订单处于 On hold 状态，备注为「does not match」：Pin Payments 报告的扣款金额或币种与订单不一致。请在 Pin Payments 后台检查该扣款，并手动退款或完成订单。
无法加载安全银行卡表单：浏览器未能从 Pin Payments CDN 加载 Pin.js，例如因为脚本拦截器，或因为会修改脚本的缓存或优化插件。请将结账页面排除在这些优化之外。
退款失败：请阅读消息。提示 TEST 或 LIVE 模式的消息表示，订单付款所用模式的私密密钥为空。Pin Payments 未确认退款表示未收到响应；请在 Pin Payments 后台检查该扣款，然后再重试。
付款失败并显示 Pin Payments 原因：Pin Payments 拒绝了扣款信息，例如金额低于该币种的最低扣款金额。顾客会看到原因，订单备注中包含错误代码。
测试付款：测试模式使用测试环境和测试密钥。请使用 Pin Payments 开发者文档中的测试卡，例如 4200 0000 0000 0000（成功）或 4100 0000 0000 0001（被拒），有效期可任意填写为未来日期，CVC 任意。订单会保留其付款时的模式，因此切换模式后，退款仍会发送到正确的环境。
错误在哪里查看：错误始终会写入 WooCommerce > Status > Logs，来源为 wcp_pinpayments_gateway。开启 Debug log 可查看每一次 API 调用。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态运行。
对开发者：过滤器 wc_ppg_supported_currencies 可更改币种列表，wc_ppg_icon 可更改 WooCommerce 付款方式列表中的图标。
卸载
停用插件会保留所有数据。若要删除，请在 Plugins 页面停用并删除该插件。本插件的许可证密钥和许可证状态始终会被删除。网关设置、插件的版本选项及其日志（包括已轮转的日志文件和数据库中的日志条目）仅在 Delete data on uninstall 开启时才会被删除；否则会保留，以便以后重新安装。订单中保存的付款数据（如 Pin Payments 扣款令牌）绝不会被删除。现有订单会保留其付款备注和交易 ID。
Pin Payments 是其各自所有者的商标。本插件与 Pin Payments 无关联，也未获得 Pin Payments 的认可。