VibeFox Khipu for Adobe Commerce — Hilfe

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

Currency: Chilean peso (CLP), Argentine peso (ARS) or Peruvian sol (PEN) as the order currency, the currency the customer sees at checkout. The base currency of the store can be another one. For orders 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 them Khipu is not shown at checkout. Nothing needs to be configured in the Khipu account.

Reachable store: Khipu confirms payments by calling your store, so the notification URL must be reachable from the internet, without password protection or a firewall blocking Khipu.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-khipu-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/KhipuPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_KhipuPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Khipu Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the Receiver ID, API key and Secret key of your Khipu collection account (see Configuration). Set Enable to Yes and click Save Config. To test first, use the keys of a Khipu developer account, then replace them with the keys of your production account.

The module adds the Khipu payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Khipu payment attempts and their notes.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Khipu Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; there are no store view settings. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters; a Sort Order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater.

The fields are one list in the group. Below they are described in the order of the page.

General

Enable: shows or hides Khipu at checkout. It is shown only when the Receiver ID, API key and secret key are all set. Default: No.

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

Description: shown in the payment method list at checkout, when the customer selects Khipu. 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, to verify every payment with Khipu and to delete unpaid payments.

Clear saved secret: API key: set it to Yes and click Save Config to remove the saved API key. It goes back to No after saving.

Secret key: used to verify the signature (HMAC-SHA256) of Khipu payment notifications. Without it no notification is accepted.

Clear saved secret: Secret key: set it to Yes and click Save Config to remove the saved secret key.

The keys are stored encrypted. A saved key is shown only as a mask (******). Leave the mask or an empty field to keep the saved key, or type a new value to replace it. An empty field does not remove a key: use the Clear saved secret field for that.

Khipu account and notifications

This row shows Copy Receiver ID, API key and secret key from your Khipu collection account. No separate sandbox host or test/live switch: use a developer account with DemoBank for testing. and Every payment sends this notification URL to Khipu; nothing needs to be configured in the account. with the notification URL of the default store view. It looks like https://your-store/wcpkhipugateway/webhook/index/. Each payment sends the same URL of the store view where the order was placed, so there is nothing to enter in your Khipu account, but the URL must be reachable from the internet.

While Enable is Yes, the row also warns Enter the Receiver ID, API key and secret key. Khipu is hidden until all three are configured. when a key is missing, and The store currency is not supported by Khipu. Supported currencies: CLP, ARS, PEN. when the currency of the default store view is not supported.

Each notification must carry a valid signature made with the Secret key of the website where the order was placed. 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:

Orders

Status after payment: the order status once Khipu confirms the payment.

Conditions

Payment from Applicable Countries: All Allowed Countries (default) or Specific Countries.

Payment from Specific Countries: with Specific Countries, Khipu is offered only when the billing address is in one of the selected countries.

Minimum Order Total and Maximum Order Total: Khipu is offered only for orders within these totals, in the base currency of the store. 0 or an empty field means no limit. Default: 0.

Sort Order: the position among the payment methods at checkout. A whole number. Default: 0.

Advanced

Debug log: logs API calls and notifications to var/log/wc_khp_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Warnings and errors are always logged, even while the switch is No. Keys, payer contacts and return tokens are never written. Default: No.

Remove data on uninstall: removes settings and log when the module is uninstalled with its data (see Uninstall). The payment history is retained. Default: No.

Log: shows the size and the latest entries (the last 50 KB) of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Khipu) and sees the Khipu logo, the description and the note You will be redirected to Khipu to complete the bank transfer. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a Khipu payment for the order total in the order currency and sends the customer to the Khipu payment page. The payment shows at Khipu as Order # with the order number and the store name (Store Name in Stores > Configuration > General > General > Store Information, or the name of the store), 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.

After paying, the customer returns to your store. 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. Magento then creates the invoice with the Khipu payment ID, sets the status from Status after payment and sends the order e-mail. The customer sees the standard order success page with Your payment with Khipu has been received.

If the bank is still verifying the transfer or Khipu cannot be reached, a Payment confirmation page shows Khipu is confirming your bank transfer. Please do not pay again. with the links Check again and Back to checkout. The order stays in Pending Payment and is confirmed by the notification as soon as Khipu confirms the transfer. The cart is not restored at this point, so Back to checkout leads to an empty cart. A customer who comes back in another browser lands on the home page.

If the customer leaves the Khipu page without paying, the payment was not completed or was reversed, or the payment does not match the order, the order is cancelled (the stock goes back), the cart is restored and the customer sees The Khipu payment was not completed. Please confirm your order again to choose a payment method. in the cart. A new attempt for the same cart deletes the previous unpaid Khipu payment, so the old link can no longer be paid. If Khipu already received the previous payment, that payment is confirmed 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 before paying again.

If Khipu cannot create the payment, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store., Khipu is temporarily unavailable. Please try again in a few minutes. or Khipu payments are not available right now. Please choose another payment method or contact the store. The details are written to the log.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its unpaid Khipu payment is deleted at Khipu and can no longer be paid. A transfer that the bank is already verifying cannot be deleted. If it is paid later, the cancelled order gets a note for manual review.

The module works with the standard Magento checkout. It takes one-off bank transfer payments only. Refunds are not sent to Khipu from Magento, and it has no subscriptions, saved payment methods or pre-authorisations. Khipu is not offered for orders created in the Admin.

Orders

Order statuses

Pending Payment: the order was placed and the customer was sent to Khipu, but Khipu has not confirmed the transfer yet. There is no invoice.

Processing or Complete: Khipu confirmed the payment. The status follows Status after payment. The invoice is created with the Khipu payment ID as the transaction ID, and a note shows Khipu payment verified. Payment ID: with the payment ID and amount.

On Hold after a mismatch: Khipu confirmed a payment whose amount or currency does not match the order total. No invoice is created. The note shows the amount expected and the amount received. The success page tells the customer Your Khipu payment needs manual review. Please contact the store. Check the payment in your Khipu account, then fulfil the order or refund the customer.

Canceled: the customer did not complete the payment, the payment could not be started, or the order was cancelled in Magento. If a payment arrives after the order was cancelled or closed, the order is not changed and gets a note asking you to review the stock and refund or reconcile the payment manually.

Closed: the payment was fully refunded with a credit memo.

If a second Khipu payment arrives for the same cart, the order is not changed. A note asks you to refund the duplicate payment to the customer. If Khipu reports a paid payment as reversed, the order gets a note and its status is not changed. The notes are order comments that the customer does not see.

Khipu payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Khipu payment ID, Requested amount (minor units), Requested currency, Received amount (minor units), Received currency and Verified via (notification, return or checkout). The customer sees only the payment method title.

The Information tab of the order also shows a Khipu payment history block with all Khipu payment attempts of the order: payment ID, Khipu status and status detail, result, requested and received amount and currency, how the payment was verified and the date. The block is read only and is shown also when the module is disabled.

Refunds

Refunds are not sent to Khipu from Magento, because Khipu offers no refund through its API. Refund the customer from your Khipu account or by bank transfer, then create a credit memo for the invoice with Refund Offline to record the refund in Magento. A full refund closes the order (Closed). An order without an invoice (On Hold after a mismatch, or a payment that arrived after cancellation) cannot be refunded in Magento; refund the customer and reconcile the order manually.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Khipu Gateway is the first row of the VibeFox Khipu Gateway group in Stores > Configuration > Sales > Payment Methods, 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 store. Below them are the line Product: magento-payment-khipu and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Khipu does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the Receiver ID, API key and Secret key are all entered. The Khipu account and notifications row shows a warning when something is missing. The order currency must be CLP, ARS or PEN. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: Khipu confirms a transfer after the bank has verified it. The order is confirmed when the Khipu notification arrives or when the customer clicks Check again. Check that your store is reachable from the internet at the URL shown in the Khipu account and notifications row (no password protection or firewall blocking Khipu), and look at the Log field. Magento maintenance mode closes the whole site, the notification URL too; Khipu sends the notification again later.

Notification answers Secret key not configured: Secret key is empty for the website of the order. 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, Payment not found for this account or Payment does not belong to this order: the payment was made to another Receiver ID or for another order, or the API key belongs to another account. Check the Receiver ID and the API key.

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 an error occurred while the order was being updated. Khipu sends the notification again. The reason is in the log.

The notification URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Khipu.

Order is On Hold after payment: read the order notes. The amount or currency did not match the order (see Order statuses).

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

There is no Refund button on the credit memo: this is normal. The module has no online refunds. Refund the customer from your Khipu account or by bank transfer, then use Refund Offline.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

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

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_KhipuPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_KhipuPayment to remove the data, then bin/magento module:disable Vibefox_KhipuPayment, delete the folder app/code/Vibefox/KhipuPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Khipu payment history is always kept. Existing orders keep their invoices, payment notes and transaction IDs.

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