VibeFox Yoco for Adobe Commerce — Помощь

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: South African rand (ZAR). Yoco accepts ZAR only. Yoco is offered only when the customer's cart is in ZAR: your base currency, or ZAR as the display currency the customer pays in. In any other currency the payment method is hidden at checkout. The order total must be at least R2.00.

Yoco account: a Yoco account with online payments. You need its secret keys, which you find in the Yoco Business Portal under Selling Online > Payment Gateway. Only the secret keys are entered. The webhook is registered by the module, and its signing secret is filled in for you.

Public site: Yoco sends webhooks to your store, so it must be reachable from the internet. The webhook URL must accept a POST without redirects.

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-yoco-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/YocoPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_YocoPayment 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 Yoco Pay 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. Paste the test secret key (sk_test_...) and, when you are ready, the live secret key (sk_live_...). Set Enable to Yes and click Save Config. The webhook is registered for each mode that has a key. Make a test payment with a Yoco test card while Test mode is Yes, then set Test mode to No to take real payments.

The module adds the Card or Instant EFT (Yoco) 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 its own tables for the Yoco payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Yoco Pay 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; Title and Description also for a store view. Remove data on uninstall is set in the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: Enter a payment method title from 1 to 128 characters. (an empty or too long Title), Sort order must be a whole number. and Order total limits must be nonnegative numbers or empty. (Minimum order total or Maximum order total).

When you save, the module checks the keys and webhook secrets and registers the webhooks. The messages about this appear at the top of the page. While Enable is Yes, the Webhooks field also shows TEST MODE — no real money is charged. in test mode, Enter the secret API key of the current Yoco mode. when the current mode has no secret key, and the reminder Yoco supports ZAR only and requires a total of at least R2.00.

General

Enable: shows or hides Yoco at checkout. It is shown only when the secret key of the current mode is set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order when the order is placed, so later changes do not rename old orders. Default: Card or Instant EFT (Yoco). Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the payment method when the customer selects it. Default: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

API keys

Copy the secret keys from the Yoco Business Portal under Selling Online > Payment Gateway. Yoco has one API for both modes: the key decides whether a payment is a test or a real one. Test mode uses only the test key, live mode only the live key.

Test mode: uses the test secret key. No real money is charged; pay with Yoco test cards. Default: Yes. Set it to No to take real payments. While it is on, customers see Test mode — no real money is charged. under the payment method.

Test secret key: the secret key of the test mode. It starts with sk_test_.

Live secret key: the secret key of the live mode. It starts with sk_live_.

Magento stores the keys and secrets encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved key or secret, clear the field and click Save Config. A key that does not start with the prefix of its field, or a webhook secret that is not whsec_ followed by base64 text, is not saved: the previous value is kept, the other settings are saved, and a warning is shown: Yoco secret was not saved: use sk_test_/sk_live_ in its matching field, or whsec_ followed by valid base64 for a webhook secret. The previous value was kept; other valid settings were saved.

Webhooks

Yoco confirms payments and refunds to the URL shown in Webhook URL in the Webhooks field. It is the storefront address of the default store view (or of the store view or website selected in Scope) and looks like https://your-store/wcpyocopay/webhook/index. You do not need to create the webhook in the Yoco portal. When you click Save Config, the module registers the URL with Yoco for each mode that has a secret key but no webhook secret, and stores the signing secret in the field of that mode. It registers the URL again when the secret key of that mode changes or the webhook URL changes; when the URL changes, the previous registration is removed first. The registration is made for the scope you save in. The page then shows Yoco: the test webhook is registered. (or live). If the registration fails, the other settings are still saved and the page shows Yoco could not register the test webhook. Payments can still be confirmed when customers return; check the key and reachable webhook URL, or enter the signing secret manually.

For each mode (Test and Live) the field shows the state of the webhook:

The module handles these events (they are also listed in the field):

Webhooks without a valid signature are rejected. An event must be signed with the secret of the store view and mode the payment was made in, so a test secret never confirms a live payment. A webhook is accepted for an order of any store view. Copy the URL exactly as the settings show it, because the webhook must reach your store without a redirect.

Test webhook secret: filled in automatically when the webhook is registered. Paste a secret (whsec_...) only if you registered the webhook URL yourself.

Live webhook secret: filled in automatically when the webhook is registered. Clear it and click Save Config to register the webhook again.

Conditions

Payment from applicable countries: All Allowed Countries offers Yoco for every country your store allows, Specific Countries only for the countries below.

Payment from specific countries: offer Yoco only for billing addresses in these countries.

Minimum order total: offer Yoco only from this order total, in the base currency of your store. Empty or 0 means no minimum. The Yoco minimum of R2.00 always applies.

Maximum order total: offer Yoco only up to this order total, in the base currency. Empty or 0 means no maximum.

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

Advanced

Debug log: writes Yoco requests and webhooks to var/log/yoco_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings, such as failed requests to Yoco and rejected webhooks, are always logged. Keys, webhook secrets and e-mail addresses are masked. Default: No.

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

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the webhooks the module registered at Yoco, the gateway settings and the log (see Uninstall). Only own settings, webhook subscriptions and log are removed: the Yoco payment attempts and refunds always stay. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Card or Instant EFT (Yoco)) and sees the description and the note You will be redirected to Yoco to complete your payment. 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 Yoco checkout for the order total in cents and sends the customer to the Yoco payment page, where the customer pays by card or Instant EFT.

After paying, the customer returns to your store. The order is marked paid only after Yoco confirms it: the module asks Yoco for the checkout when the customer comes back and again when the signed webhook arrives. Magento then creates the invoice with the Yoco payment ID, the order moves to Processing, the order e-mail is sent, and the customer sees the standard order success page. If Yoco has not confirmed the payment yet when the customer comes back, a Payment confirmation page shows Your payment has not been confirmed by Yoco yet. Please do not pay again while confirmation is pending. with the buttons Check again and Back to checkout. The webhook confirms the order as soon as it arrives. The return link works only in the browser session that placed the order; in another browser the customer lands on the home page.

If the customer cancels on the Yoco page or the payment fails, the module checks with Yoco that the checkout is not paid, cancels the order (the stock goes back), restores the cart and shows The Yoco payment was not completed. Your cart is saved; you can try again or choose another payment method. The Yoco checkout itself cannot be cancelled through the Yoco API and may stay payable at Yoco. A payment that arrives later for the cancelled order is only noted for you (see Orders and refunds).

Before a new payment attempt for the same cart the module checks the earlier attempts with Yoco. If the same order is still open at Yoco for the same amount and mode and was created less than 30 minutes ago, the customer gets the same Yoco page again. If an earlier attempt of this order is already paid, the order is confirmed without a new payment page. If the cart was already paid with another order, the customer sees Another Yoco checkout for this quote was already paid. Please do not pay again.

If the payment cannot be started, for example because the current mode has no key, the total is below R2.00 or Yoco refuses the request, the order is cancelled, the cart is restored and the customer sees a message in the cart, for example Yoco requires its current-mode key, ZAR, a total of at least R2.00 and the configured country/amount limits. or Yoco did not confirm checkout creation. Retry the same order after checking the payment status. The order gets the note The Yoco payment page could not be created. If Yoco does not answer at all, it is not known whether the checkout was created: the order stays in Pending Payment and the customer sees the Payment confirmation page with The Yoco payment requires confirmation or manual review. Please do not pay again; contact the store if this continues. Such an order can be cancelled by you or by the Magento cron like any other waiting order.

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), the module first asks Yoco whether the checkout is unpaid. The Yoco API cannot cancel a checkout, so it may stay payable at Yoco; a payment that arrives later is noted on the cancelled order for you to reconcile. If Yoco never answered the checkout request, no payment page reached the customer: the order is cancelled with a note. If Yoco cannot be reached or the secret key of the payment's mode is missing, the cron still cancels the order and adds the note Yoco could not confirm that checkout … is unpaid when the order was cancelled., while a cancellation in the Admin is refused with Yoco has not confirmed an unpaid checkout. Cancellation was refused; check the order. so you can check the payment first. If Yoco reports the checkout as paid, the order is not cancelled, and the payment is confirmed by the webhook or the customer's return. In the Admin you see Yoco reports this checkout as paid. The order was not cancelled; check the order.

The module works with the standard Magento checkout. Payments are charged immediately on the Yoco page. It has no saved cards, subscriptions or recurring payments, no on-site card form and no separate authorize and capture, and it does not work in currencies other than ZAR. Yoco is not offered for orders created in the Admin.

Orders and refunds

Order statuses

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

Processing: the payment was confirmed. The invoice is created with the Yoco payment ID as the transaction ID, and a note shows the amount, the Yoco checkout and payment IDs, the mode and how the payment was confirmed (the customer's return, the webhook or a check before a new payment attempt).

On Hold after a mismatch: Yoco reported a different amount or currency than the order total. No invoice is created. The note Yoco amount/currency mismatch shows the amount expected and the amount received. Check the payment in the Yoco portal before shipping. If a correct payment of the order is confirmed later, the order is released and invoiced.

Canceled: the customer cancelled or did not complete the payment, the payment could not be started, or the order was cancelled in Magento. A payment that arrives for a cancelled or refunded order does not change it. A note asks you to reconcile it in the Yoco portal.

Closed: the payment was fully refunded with credit memos.

If a second payment arrives for an order that is already paid, or a payment arrives for another order of a cart that is already paid, the order is not changed. A note asks you to reconcile the extra payment in the Yoco portal. The notes are order comments that the customer does not see.

Yoco payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for each payment attempt of the cart, Yoco checkout attempt with the checkout ID, the payment ID, the mode, the status and the amount, and for each refund Yoco refund with the refund ID, the status, where it was made (Magento or the Yoco portal), the mode and the amount. The block is shown also when the module is disabled. The customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Yoco. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Yoco.

The refund is made in ZAR, up to the amount Yoco charged minus the amounts already refunded; a larger refund is refused with Refund exceeds the remaining original Yoco payment amount. The refund is sent in the mode the payment was made in (test or live), so that mode's secret key must be set. If Yoco refuses the refund or does not answer, Magento shows the error and the credit memo is not created, for example Yoco did not confirm the refund. No Credit Memo was saved. Check the payment and retry the same amount. A refund repeated with the same items and amounts after a lost answer is not paid out twice. After a successful refund the credit memo is saved with the Yoco refund ID as the transaction ID. A full refund closes the order. Refunds are available once Yoco has confirmed the payment and the order has an invoice.

If Yoco reports the refund as pending, Magento shows Yoco accepted the refund, but it is pending. Its signed webhook will create the native Credit Memo; do not repeat it. and no credit memo is created yet. When Yoco confirms the refund by webhook, the module creates the credit memo with the same items and amounts. Until then, other refunds of the order are refused with An earlier Yoco refund is pending or unconfirmed. Retry its same amount or wait for its webhook before another refund.

Refunds made in the Yoco portal arrive by the refund.succeeded webhook. The module creates an offline credit memo for the refunded amount with the comment that the money was already returned by Yoco; no second refund is sent. A partial portal refund is recorded as an amount without returning items to stock. When the portal refunds reach the amount paid, the order is closed. A refund larger than the amount left to refund is not recorded, and a note asks you to check the order. A failed refund adds the note Yoco refund with its ID and failed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Yoco Pay Gateway is the first row of the VibeFox Yoco Pay 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-yoco 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, Yoco 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, and refunds work.

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

Yoco does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has a secret key: Test secret key in test mode, Live secret key in live mode. The Webhooks field shows a warning when the key is missing. The cart must be in ZAR and the total at least R2.00. 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: the webhook is not working. Look at the Webhooks field for the mode you use. If it is not registered, or registered for another URL, click Save Config. If the registration fails, the page shows a warning. If you entered the secret yourself, check that it belongs to the webhook of this URL and mode. The order is also confirmed when the customer returns to the store after paying, and when the customer tries to pay the same cart again.

Could not register the webhook: payments are still confirmed when customers return to the store. Check the secret key and that the store is reachable from the internet over HTTPS, and save again. You can also register the URL yourself and paste the signing secret.

Webhooks are rejected: the answers of the webhook URL are shown in the Yoco portal and rejected webhooks are written to the log. webhook secret not configured means no webhook secret is set. missing signature headers means the request was not sent by Yoco. invalid signature or timestamp outside the tolerance means the secret belongs to another registration or mode, or the server clock is wrong: signatures are accepted within 5 minutes of the server time. An answer of 409 (open) or 503 is temporary; Yoco sends the webhook again.

The webhook URL shows POST required in the browser: this is normal. The URL accepts only requests from Yoco.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Yoco retries the webhook later, and the order is also confirmed when the customer returns.

Yoco secret was not saved warning on save: a key was pasted into the wrong field. The test key starts with sk_test_, the live key with sk_live_, a webhook secret with whsec_. The previous value was kept.

The customer is back in the cart with an error after Place Order: look at the Log field in the Advanced section. The order of that attempt is cancelled. Yoco is temporarily unavailable. Try again later. means an unexpected error; the reason is in the log.

The customer is told a payment needs confirmation or manual review: Yoco did not answer the checkout request, or an attempt was paid with a different amount, after the order was cancelled, or twice. Read the order notes and the payment information, check the payment in the Yoco portal, then fulfil the order or refund the payment there.

The order cannot be cancelled in the Admin: Yoco could not confirm that the checkout is unpaid, for example because Yoco cannot be reached or the secret key of the mode of the payment was removed. Check the payment in the Yoco portal and the key, then try again. The Magento cron cancels such orders after the Pending Payment Order Lifetime with a note and does not stop on them.

Refund fails with The API key of the original Yoco payment mode is not configured.: the payment was made in test or live mode, and the secret key of that mode is not set. Enter it and try again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded online; refund it in the Yoco portal.

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.

Developers: the event yoco_p_checkout_payload lets another module change the request that creates the Yoco checkout. The amount, currency, return addresses and order references cannot be changed.

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_YocoPayment. It removes the data and the code.

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the module also tries to delete the webhooks it registered at Yoco, and removes the gateway settings and the log. If it is No, the settings and the webhooks are kept for a re-install. The Yoco payment attempts and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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