VibeFox Khipu for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. Without WooCommerce the plugin refuses to activate.

PHP: 8.0 or later.

Store currency: Chilean peso (CLP), Argentine peso (ARS) or Peruvian sol (PEN). The payment method is hidden at checkout when the store, or the order on the Pay for order page, uses another currency.

Khipu account: you need the Receiver ID ("Id de cobrador"), the API key and the secret key ("llave") 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.

Reachable site: Khipu confirms payments by calling your store, so the site must be reachable from the internet (no maintenance mode, basic authentication or firewall blocking Khipu).

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

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_khipu_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Khipu > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

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

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

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Khipu. 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 store currency is not supported. In the list of payment methods, Khipu is marked as needing setup until all three keys are entered.

General

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

Title: the payment method name customers see at checkout. Default: Khipu.

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 plugin 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.

Payment notifications

Khipu confirms payments by calling the notification URL shown in this section of the settings. It looks like https://your-site/wc-api/webhook_wc_khipu/. 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. Then the plugin asks Khipu for the payment status and acts on what Khipu reports:

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

done, reversed: the payment was reversed. An unpaid order is not marked paid. A paid order gets a note, and its status is not changed.

pending or verifying: the transfer is not final yet. The plugin 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 and one set of e-mails.

Processing: lets WooCommerce decide (default). Virtual downloadable orders are completed automatically.

Completed: every paid order becomes Completed.

Advanced

Debug log: Log API calls and notifications in WooCommerce > Status > Logs, source wcp_khipu_gateway. Errors are always logged. Keys and payer data are never written. Default: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Order data (Khipu payment IDs in orders) is always kept. Default: off.

Checkout

The customer chooses the payment method (by default Khipu) and places the order. The plugin creates a Khipu payment for the order total in the order currency, with the order number, the store name and the ordered items, and sends the customer to the Khipu payment page. The billing e-mail is passed to Khipu when it is valid. On the Khipu page the customer pays by bank transfer from their own bank and chooses there between the transfer types Khipu offers.

After paying, the customer returns to the order received page of your store. The order is marked paid only after Khipu confirms the transfer: by the signed notification, or by a status request to Khipu when the customer opens the order received page. The return itself never marks an order as paid. While the transfer is not confirmed, the page shows Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.

If the customer leaves the Khipu page without paying, the customer lands on the Pay for order page with The Khipu payment was not completed. You can try again or choose another payment method. 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 completed and no new payment is created. 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.

With stock management on, the Khipu payment expires together with the WooCommerce Hold stock (minutes) time, so the customer cannot pay an order that was already cancelled.

If Khipu cannot create the payment, the customer sees 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 payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-off bank transfer payments only. Refunds from WooCommerce are not supported, and it has no subscriptions, saved payment methods or pre-authorisations.

Orders

Order statuses

Pending payment: the customer was sent to Khipu and has not paid yet, or Khipu has not confirmed the transfer yet. The order note shows the Khipu payment ID.

Processing or Completed: Khipu confirmed the payment. The status follows Status after payment. The order note shows the Khipu payment ID, and the transaction ID is the Khipu payment ID.

On hold: Khipu reported a payment whose amount or currency does not match the order, or the payment arrived after the order had been cancelled (for example after the hold stock time). The order note explains it. Check the payment in your Khipu account and complete the order or refund the customer.

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.

Refunds

Refunds are not sent to Khipu from WooCommerce. Refund the customer from your Khipu account or by bank transfer, then record the refund in WooCommerce manually.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Khipu. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 store currency must be CLP, ARS or PEN. The settings page shows a warning when something is missing.

The payment went through, but the order stays Pending payment: Khipu confirms a transfer after the bank has verified it. The order is updated when the Khipu notification arrives or when the customer opens the order received page. Check that your site is reachable from the internet at the notification URL shown in the settings (no maintenance mode, basic authentication or firewall blocking Khipu), and look at WooCommerce > Status > Logs, source wcp_khipu_gateway.

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 Payment does not belong to this order: the payment was made to another Receiver ID or for another order. 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.

Order is On hold: read the order note. 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

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

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

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