VibeFox Paystack for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

货币：订单必须使用 Paystack 支持的货币：NGN、USD、GHS、ZAR、KES、XOF、EGP 或 RWF，具体取决于您的 Paystack 账户已启用的货币。使用其他货币时，付款方式会被隐藏。在 XOF 和 RWF 中，Paystack 仅接受整数金额。

Paystack 账户：您需要 Paystack 账户的密钥：测试密钥（sk_test_...）和/或正式密钥（sk_live_...）。无需公钥（pk_...），因为付款在 Paystack 托管的页面上完成。您还需要在 Paystack 后台设置店铺的 Webhook URL（参见「配置」）。您的店铺必须可从互联网访问，才能接收 Webhook。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先在电脑上解压。其中包括 README.txt、OpenCart 3 安装包 wcp_paystack_payment-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_paystack_payment.ocmod.zip。只安装与您 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_paystack_payment-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Paystack Payment，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见「许可证密钥」）。

4. 粘贴 Paystack 后台的密钥，并在 Paystack 后台设置 Webhook URL（参见「配置」）。

5. 开启 Enable/Disable，然后点击 Save。在完成一次测试付款之前，请保持 Test Mode 开启；之后关闭它即可接受真实付款。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_paystack_payment.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中读取扩展代码，重命名后的安装包无法使用。

2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Paystack Payment，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的第 3–5 步输入许可证密钥、Paystack 密钥和 Webhook。设置页面及其字段在两个版本中相同。仅 Webhook URL 不同（参见「Webhook」）。

新安装时，付款方式默认关闭，测试模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Paystack Payment > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。设置上方的状态框会显示当前模式：测试模式：不会扣除真实资金。或正式模式：将接受真实付款。当当前模式的密钥为空、在密钥字段中输入了公钥（pk_...）、正式模式使用了测试密钥（sk_test_...）或测试模式使用了正式密钥（sk_live_...），以及 Paystack 不接受店铺默认货币时，状态框也会发出警告。只要存在密钥问题，结账时就会隐藏该付款方式。如果您没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 不能为空，也不能超过 128 个字符；Sort Order 必须是整数；Total 必须是大于或等于 0 的数字；地区（geo zone）和订单状态必须存在；否则不会保存任何内容。密钥问题不会阻止保存：状态框会指出具体问题。

Paystack

本节开头有一段简短说明：Paystack 托管付款页面支持银行卡、银行转账、USSD 和移动支付；每笔付款都通过 Paystack API 在服务器端确认；并列出可接受的货币。

Enable/Disable：Enable Paystack Payment 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Paystack。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely using your debit card, credit card, or bank account via Paystack.

Sort Order：Paystack 在结账付款方式中的排列位置。可留空或输入整数。

Geo Zone：仅向所选地区（geo zone）内的付款地址提供 Paystack。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的结账金额（以店铺默认货币计算），才会提供 Paystack。留空则对任何金额都提供 Paystack。

API 密钥

从 Paystack 后台的 Settings > API Keys & Webhooks 页面复制密钥。本节包含指向该页面的链接。

Test Mode：新付款使用测试密钥，不会扣除真实资金。关闭后，将使用正式密钥接受真实付款。在另一种模式下完成的付款，在核验和退款时仍使用其所属模式的密钥。默认：开启。开启时，顾客在 Confirm Order 步骤会看到测试模式已启用。不会产生真实扣款。

Test Secret Key：您的 Paystack 测试密钥，以 sk_test_ 开头。

Live Secret Key：您的 Paystack 正式密钥，以 sk_live_ 开头。

已保存的密钥不会再次显示。该字段保持为空，并显示已保存——留空即保留原值。只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved value，然后点击 Save。

Webhook

即使顾客没有返回店铺，Webhook 也会告知店铺付款已完成。在 Paystack 后台的 Settings > API Keys & Webhooks 页面中，将本节 Webhook URL 显示的 URL 同时设置为 Test Webhook URL 和 Live Webhook URL。在 OpenCart 3 中它的格式为 https://your-store/index.php?route=extension/payment/wcp_paystack_payment/webhook，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_paystack_payment/payment/wcp_paystack_payment.webhook，由您的 OpenCart 安装的店铺前台地址生成。请完全按照设置中显示的内容复制 URL。

Paystack 会用您的密钥为每个 Webhook 签名，因此无需进行其他配置。没有有效签名的 Webhook 会被拒绝。扩展使用 charge.success 事件：

其他事件会返回 OK 并被忽略。没有 Webhook 时，只有顾客付款后返回店铺，订单才会被确认。之后才完成的银行转账和 USSD 付款，只能通过 Webhook 确认。

订单

OpenCart 在 Confirm Order 步骤创建订单时不设置状态（缺失订单，即 missing order）。只有在 Paystack 通过 API 确认付款后，订单才会获得状态。下方每个状态字段都列出您的 OpenCart 订单状态。

Autocomplete Order：开启后，已付款订单会使用 Complete Order Status，而不是 Paid Order Status。默认：关闭。

Paid Order Status：付款确认后设置的状态。默认：Processing。

Complete Order Status：Autocomplete Order 开启时，付款确认后设置的状态。默认：Complete。

Awaiting Payment Status：顾客在 Paystack 仍在处理付款时返回（银行转账、USSD、移动支付）。在 Webhook 确认付款之前，订单保持此状态。默认：Pending。

On Hold (Review) Status：付款需要您审核（参见「订单状态」）。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Failed Status：Paystack 仍在处理的付款，对于处于等待状态的订单失败了。默认：Failed。

Refunded Status：付款已在订单页面全额退款。默认：Refunded。

高级

Debug log：将 Paystack 事件和 API 调用写入 OpenCart 日志文件夹（storage/logs）中的 paystack_p_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会移动为 paystack_p_debug.old.log.php。错误和警告始终会被记录。密钥和顾客数据从不记录。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Delete data on uninstall：开启后，卸载扩展会删除网关设置和日志。订单中保存的付款数据始终保留。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的密钥会保留。

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 Paystack）。在 Confirm Order 步骤，顾客会看到您的说明，以及提示您将被重定向到安全的 Paystack 页面以完成付款。 OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客通过付款方式区块的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。当顾客点击 Confirm Order 时，扩展会以订单货币为订单总额发起一笔 Paystack 交易，附带顾客的电子邮件，并将顾客带到 Paystack 托管的结账页面。顾客在该页面使用您 Paystack 账户中已启用的渠道之一付款。付款信息包含订单号和顾客姓名。

付款后，顾客返回您的店铺。只有在 Paystack 确认付款后，订单才会被标记为已付款：当顾客返回时，以及 Webhook 到达时，扩展都会通过 Paystack API 读取交易，并检查参考号、状态、金额和货币。随后，订单会以标准的 OpenCart 方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 订单成功页面。

如果付款仍在处理中，例如银行转账，顾客返回时订单会获得 Awaiting Payment Status，成功页面显示谢谢。您的付款正在由 Paystack 确认；您将收到一封确认邮件。 Webhook 会在之后完成订单，当订单变为已付款或付款失败时，顾客会收到 OpenCart 订单状态邮件。对于处于审核中的订单，成功页面显示我们已收到您的付款，订单正在审核中。如有需要，我们会与您联系。 如果顾客返回时无法连接 Paystack，或 Paystack 尚未确认付款，Payment confirmation 页面会请顾客不要重复付款，并提供 Check again 和 Back to checkout 选项；Webhook 一到达就会设置订单状态。

如果顾客在 Paystack 页面点击 Cancel payment、未付款就离开，或付款被拒绝，订单会保持无状态，购物车会被保留。顾客返回结账页面，并显示消息：付款已取消。您可以重试，或选择其他付款方式。、付款未完成。您可以重试，或选择其他付款方式。或您的付款被拒绝。您可以重试，或选择其他付款方式。 在 OpenCart 4 中，这些消息显示在结账页面上方。

每次新的尝试（OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则更新结账中的订单）都会发起一笔新的 Paystack 交易。较早的付款页面仍然有效：如果之后被付款，仍会接受该付款。在发起新付款之前，会向 Paystack 核查同一购物车在过去 24 小时内的未完成尝试。如果购物车已付款、正在审核或等待银行转账，顾客会直接进入成功页面，不会发起第二笔付款。如果同一购物车的另一笔订单仍被付款，该订单将保持无状态，而已付款的订单会收到一条备注，提示退还重复付款。购物车的任何变动（包括新的数量）都视为需要单独付款的新购物车。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单在此期间未付款即被关闭（例如您取消了它），顾客会被送回结账页面，并显示消息 您之前的订单已在未付款的情况下取消。请重新确认订单，以新订单付款。 下一次 Confirm Order 将为新订单付款。如果该订单此前已为较早的购物车付款，而购物车之后发生了变化，顾客会被带回结账页面，下一次 Confirm Order 将为当前购物车的新订单付款。已关闭的订单绝不会显示为已付款。

返回链接只能与其自身的随机令牌配合使用。无法与订单匹配的返回，会将顾客带回结账页面，并显示无法将此付款与订单匹配。如果您被扣款，请与我们联系。

如果 Paystack 无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短消息，例如 Paystack 无法发起付款：后接 Paystack 给出的原因，或Paystack 暂时不可用。请稍后重试，或选择其他付款方式。 订单总额必须大于零，并且顾客需要提供有效的电子邮件地址。

即使店铺处于维护模式，Webhook 也能正常工作，因为 OpenCart 会放行付款扩展的请求（在 OpenCart 4 中，扩展会为此添加自己的启动动作，该动作同时允许顾客从 Paystack 返回）。

该扩展没有嵌入式或弹出式付款表单，不保存银行卡，不支持订阅、分单或子账户，也不支持在 OpenCart 中选择付款渠道。

订单与退款

订单状态

无状态（缺失订单）：顾客已被带到 Paystack，但尚未付款、已离开 Paystack 页面，或 Paystack 尚未确认付款。在 Sales > Orders 中，这类订单只有在 Order Status 筛选条件设为 Missing Orders 时才会显示。

Awaiting Payment Status（默认 Pending）：顾客在 Paystack 仍处理付款（例如银行转账或 USSD）时返回。Paystack 确认付款后，订单会转为已付款状态。如果这类付款始终未完成，订单会保持此状态，直到您进行更改。

Paid Order Status（默认 Processing）或 Complete Order Status：付款已确认。Autocomplete Order 开启时使用完成状态。备注会显示金额、Paystack 参考号、交易编号、模式（测试或正式）、付款渠道、银行卡类型和银行卡付款的末几位数字，以及顾客支付的任何 Paystack 手续费。

On Hold (Review) Status（默认 Pending）：实付金额或货币与订单不一致（备注为 Paystack amount or currency mismatch），或者付款是在订单已被取消或在未付款的情况下改为其他状态之后到达的。备注会说明需要检查的内容。请处理订单或退还付款。

Failed Status（默认 Failed）：Paystack 报告，处于等待状态的订单的最近一次付款尝试失败或被撤销。较早尝试的失败不会改变订单。

如果已付款的订单又收到第二笔付款，订单不会被修改。备注会提示您在 Paystack 后台退还重复付款。对于处于其他处理状态（例如 Shipped）的订单收到的付款，只会在订单上做记录。

备注是订单 History 中的条目，顾客看不到。

VibeFox Paystack Payment 选项卡

在 Sales > Orders 中打开一个通过 Paystack 付款的订单。在订单页面底部，与 History 和 Additional 并列，VibeFox Paystack Payment 选项卡会显示 Transaction reference、测试付款带有 Test 标签的 Mode、付款的 Status、Transaction ID、Channel 和 Card、付款日期、Paid / refunded 金额、退款表单、退款历史以及订单的 Paystack notes。该选项卡对有权访问扩展的用户可见。

退款

在 VibeFox Paystack Payment 选项卡中，输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Paystack。确认提示通过 Paystack 退还此金额？此操作无法撤销。支持全额和部分退款。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。退款会退到支付该订单的交易，并使用付款时所在模式（测试或正式）的密钥，因此该模式的密钥必须已设置。退款以 Paystack 实际扣款的金额和货币进行；因此，对于因金额或货币不一致而处于审核中的订单，您最多只能退还顾客实际支付的金额，而不是订单总额。在 XOF 和 RWF 中，退款必须是整数金额。

Paystack 会将退款排队处理：备注和退款历史会显示 Paystack 返回的状态（例如 pending）以及退款 ID。如果 Paystack 不接受退款，选项卡会显示 Paystack refund failed: 及原因，并且不会记录任何退款。全额退款会将订单设为 Refunded Status，不会通知顾客，也不会把商品退回库存，与手动更改状态一样。部分退款不会改变状态。Paystack 确认付款后，退款功能即可使用。

在 Sales > Returns 中的商品退货不会通过 Paystack 退款。在 Paystack 后台进行的退款，以及 Paystack 排队处理的退款的最终状态，不会同步回 OpenCart。如有需要，请手动记录。

许可证密钥

该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Paystack Payment 是 Extensions > Extensions > Payments > VibeFox Paystack Payment > Edit 中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方有 Product: opencart-payment-paystack 一行，以及 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 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 Paystack。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该付款方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥前完成扩展的设置和测试。在 OpenCart 4 中此预览不可用：店铺看不到管理员登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也仍可进行。

许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时，状态会自动重新检查：在输入密钥后的前 14 天每天一次，之后每周一次。无需设置计划任务（cron）。卸载扩展时，许可证密钥和许可证状态总会被删除。

故障排除

结账时不显示 Paystack：请检查许可证是否有效，Enable/Disable 是否开启，当前模式是否有正确的密钥（测试模式使用 sk_test_... 的 Test Secret Key，正式模式使用 sk_live_... 的 Live Secret Key），以及订单货币是否为 Paystack 支持的货币。设置顶部的状态框会指出问题。另外还要检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Webhook 没有到达您的店铺，而且顾客也没有返回。请在 Paystack 后台检查 Test Webhook URL 和 Live Webhook URL 是否与 Webhook URL 中显示的 URL 完全一致，并确认没有防火墙或密码保护阻止它。开启 Debug log，并查看 Log 字段中被拒绝的 Webhook。

Webhook 返回 Invalid signature：Webhook 没有使用设置中输入的测试或正式密钥签名，例如因为这些密钥属于另一个 Paystack 账户。请输入发送 Webhook 的那个账户的密钥。

Webhook 返回 Secret key not configured：未设置任何密钥。请在设置中输入密钥。

Webhook 返回 Verification failed、Busy、retry later 或 Order could not be updated, retry later：此时无法通过 Paystack API 读取交易，或顾客返回的操作同时在处理同一购物车，或无法设置订单状态。Paystack 会重新发送 Webhook。日志会显示原因。

Webhook 返回 OK - unknown reference：该付款不是为本店铺的订单做的，例如 Paystack 付款页面，或同一账户上的其他集成。该付款会被忽略。

Webhook URL 在浏览器中显示 Empty body：这是正常现象。该 URL 只接受来自 Paystack 的请求。

顾客看到 Payment gateway is not properly configured：当前模式的密钥缺失或错误。请按设置顶部状态框的提示进行修正。Confirm Order 后出现 This payment method is not available.，表示付款方式期间已被关闭，或结账页面已与订单不一致：顾客需要重新加载结账页面。

付款后订单处于审核状态：请阅读 VibeFox Paystack Payment 选项卡中的备注（参见「订单状态」），然后处理订单或退还付款。

订单停留在等待状态：Paystack 尚未确认付款。请在 Paystack 后台检查该交易以及 Webhook 设置。如果顾客从未完成付款，请手动更改状态。

选项卡中没有退款表单：选项卡会说明原因：付款尚未确认、已全额退款、您的用户组没有修改扩展的权限，或付款所在模式的密钥缺失。

退款失败并提示模式相关信息：付款是在测试或正式模式下完成的，而该模式的密钥尚未配置。请输入密钥后重试。

对开发者：扩展会触发 OpenCart 事件 paystack_p_payment_request（交易请求）、paystack_p_supported_currencies 和 paystack_p_currency_decimals。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Paystack Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态（重新安装时会恢复为默认值）。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中同时删除其事件以及在维护模式下允许 Webhook 和顾客返回的启动动作）。如果 Delete data on uninstall 已开启，则其余网关设置（标题、说明、测试模式、密钥、自动完成、日志记录）和日志会被删除。如果已关闭，这些设置会保留，供以后重新安装时使用。订单的 Paystack 付款数据和退款总会被保留，因此之前付款的订单在重新安装后仍可退款。已有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Paystack Payment 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

Paystack 是其各自所有者的商标。本扩展与 Paystack 无关联，也未获得 Paystack 的认可。