VibeFox Khipu for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Currency: Chilean peso (CLP), Argentine peso (ARS) or Peruvian sol (PEN). For carts in other currencies the payment method is hidden at checkout.

Khipu account: you need the Receiver ID ("Id de cobrador"), the API key and the secret key of your Khipu collection account. You find them in your Khipu account under the merchant profile (khipu.com/merchant/profile). All three are required: without the secret key no payment can be confirmed. Nothing needs to be configured in the Khipu account.

Reachable shop: Khipu confirms payments by calling your shop, so the notification URL must be reachable from the internet, without password protection or a firewall blocking Khipu. Maintenance mode of the shop does not block it.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Khipu Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter the Receiver ID, API key and Secret key of your Khipu collection account (see Configuration).

5. Turn on Enable / Disable and click Save. To test first, use the keys of a Khipu developer account, then replace them with the keys of your production account.

On install the module creates the order status Khipu payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Khipu Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when the Receiver ID, API key or secret key is missing (Khipu is then not offered at checkout) and when the default currency of the shop is not supported by Khipu.

Khipu

Enable / Disable: Enable Khipu payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Khipu. Required.

Description: the text shown under the payment method at checkout. Default: Pay by bank transfer with Khipu.

Khipu account

Copy the Receiver ID, API key and secret key from your Khipu collection account (khipu.com/merchant/profile). Khipu has no separate sandbox server and the module has no test mode switch. To test, use the keys of a developer ("desarrollo") collection account: it pays with the DemoBank test bank, and no real money is moved. Switch to the keys of your production collection account when you go live.

Receiver ID: your Khipu Receiver ("cobrador") ID. Payments of other Khipu accounts are rejected.

API key: used to create payments and to verify every payment with Khipu.

Secret key: used to verify the signature (HMAC-SHA256) of Khipu payment notifications. Without it no payment can be confirmed.

Saved keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick API key or Secret key and click Save to remove it. An empty field keeps the saved value.

Payment notifications

Notification URL: Khipu confirms payments by calling the URL shown here. With friendly URLs it looks like https://your-shop/module/wcp_khipu_gateway/webhook, possibly with a language code. The URL is sent automatically with every payment, so there is nothing to configure in your Khipu account, but the URL must be reachable from the internet.

Each notification must carry a valid signature made with your Secret key. Notifications without a valid signature are rejected. The module never trusts the content of the notification: it asks Khipu for the payment status and acts on what Khipu reports:

done: the transfer was confirmed. The order is created after the Receiver ID, cart and amount checks.

done, reversed: the payment was reversed. No order is created for an unpaid cart. A paid order gets a note, and its status is not changed.

pending or verifying: the transfer is not final yet. The module answers "retry later", and Khipu sends the notification again.

Status after payment: the order status once Khipu confirms the payment. The status is set at once, with one status change.

Processing: the order gets Payment accepted (default).

Completed: the order gets Delivered.

Advanced

Debug log: logs API calls and notifications to logs/wc_khp_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged, even while the switch is off. Keys and payer data are never written. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the module removes the gateway settings and the log. Order data (Khipu payment IDs of orders) is always kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Khipu) with its description and confirms the order. The module creates a Khipu payment for the cart total in the cart currency and sends the customer to the Khipu payment page. The payment shows at Khipu as Order # with the cart number and the shop name, with the list of products. The customer's e-mail is passed to Khipu when it is valid. On the Khipu page the customer pays by bank transfer from their own bank. No order exists yet at this point.

After paying, the customer returns to your shop. The order is marked paid only after Khipu confirms it: by the signed notification, or by a status request to Khipu when the customer comes back. The return itself never marks anything as paid. Once the order is created, the customer sees the standard order confirmation page. If the bank is still verifying the transfer or Khipu cannot be reached, a Payment confirmation page shows Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail. with the buttons Check again and Back to checkout. If the latest Khipu payment of the cart cannot be matched to it (for example, it belongs to another Receiver ID), the customer is back at checkout with We could not match this payment to an order. If you paid, please contact us.

If the customer leaves the Khipu page without paying, or the payment was not completed, the customer is back at checkout with The Khipu payment was not completed. You can try again or choose another payment method. The cart is kept. A new attempt deletes the previous unpaid Khipu payment, so the old link can no longer be paid. If Khipu already received the previous payment, the order is created and no new payment is made. If the previous transfer is still being verified, the customer sees Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again.

If Khipu cannot create the payment, the customer stays at checkout with a short message, for example Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. or Khipu is temporarily unavailable. Please try again in a few minutes. The details are written to the log.

The notification works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module takes one-off bank transfer payments only. Refunds are not sent to Khipu from PrestaShop, and it has no subscriptions, saved payment methods or pre-authorisations. Unpaid payments are not tied to a stock reservation.

Orders

Order statuses

No order yet: the customer was sent to Khipu and has not paid, or Khipu has not confirmed the transfer yet. Only the cart exists.

Payment accepted or Delivered: Khipu confirmed the payment. The status follows Status after payment. The payment is recorded with the Khipu payment ID as the transaction ID, and a note shows Khipu payment verified. Payment ID: with the payment ID and amount.

Khipu payment on hold: Khipu confirmed a payment whose amount or currency does not match the order (for example, the cart was changed after the payment started), or the payment arrived after the order had been cancelled. The amount actually received is recorded on the order (not when the currency differs), and a note explains it. Check the payment in your Khipu account, then complete the order or refund the customer. If a later payment of the right amount arrives for the same cart, the order moves to the paid status.

If a payment arrives for an order that is already paid or was closed after payment, the order is not changed. A note asks you to refund it to the customer if it is a second payment. If Khipu reports a paid payment as reversed, the order gets a note and its status is not changed.

Khipu payment block

The order page shows a Khipu payment block with the Khipu payment attempts of the order's cart (date, amount, Khipu payment ID, Khipu status and result), a Manual review warning while the order is Khipu payment on hold, and the Khipu notes of the order. The block is read only.

Refunds

Refunds are not sent to Khipu from PrestaShop, because Khipu offers no refund through its API. Refund the customer from your Khipu account or by bank transfer, then record the refund in PrestaShop manually.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Khipu Gateway is the first block on Modules > Module Manager > VibeFox Khipu Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-khipu and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Khipu is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

Khipu does not appear at checkout: check that the license is active, Enable / Disable is on and the Receiver ID, API key and Secret key are all entered. The cart currency must be CLP, ARS or PEN. The settings page shows a warning when something is missing. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: Khipu confirms a transfer after the bank has verified it. The order is created when the Khipu notification arrives or when the customer clicks Check again. Check that your shop is reachable from the internet at the URL shown in Notification URL (no password protection or firewall blocking Khipu), and look at the Log field on the module page.

Notification answers Secret key not configured: Secret key is empty. Enter it. Khipu sends the notification again.

Notification answers Invalid signature, Missing signature or Malformed signature: the Secret key does not belong to the collection account whose keys you use, or the request did not come from Khipu.

Notification answers Order not found or Payment does not belong to this order: the payment was made to another Receiver ID or for another cart. Check the Receiver ID.

Notification answers Payment not final yet or Verification unavailable: the transfer is still being verified, or Khipu could not be reached. Khipu sends the notification again.

Notification answers Busy, retry later or Order could not be created, retry later: the order was being confirmed by another request at the same moment, or the order could not be created (for example, the module is disabled). Khipu sends the notification again. The reason is in the log.

Order is Khipu payment on hold: read the notes in the Khipu payment block. The amount or currency did not match the order, or the payment arrived after the order had been cancelled.

The customer sees "Khipu payments are not available right now": the API key is missing or wrong. Check the keys in your Khipu account.

If your Khipu account accepts another currency, for example EUR for Khipu Spain, developers can add it with the hook actionWcpKhipuSupportedCurrencies.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Khipu Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the gateway settings and the log are removed. If it is off, all settings are kept for a later re-install. The Khipu payment attempts and the order status Khipu payment on hold are always kept. Existing orders keep their payment notes and transaction IDs.

Khipu is a trademark of its respective owner. This module is not affiliated with or endorsed by Khipu.