Having trouble with your online payments? These troubleshooting steps will help you get back to accepting payments, fast.
Plugin issues
Plugin not displaying on your website
It’s important to check your setup, because your plugin won’t work if it hasn’t been correctly configured. Start by completing these checks.
→ API keys
Are you sure you’re using the right API keys? Your Test and Live keys must be configured properly. Follow the steps for WooCommerce here , for Wix here, or keep reading to make sure you’re on the right track.
💡 Good to know: This check does not apply for Shopify plugin users. Shopify handles all API integration themselves, so it’s automatically part of your installation.
🔑 Which key does what?
Test keys are for safely testing how the Yoco Gateway works on your website. Test keys can only be used with the test card details, which are also provided on the Payment Gateway tile/widget in the Yoco App (mobile or web).
Live keys are for when you’re ready to take real transactions from real customers. When you’re ready to go live, swap to Live keys.
Public vs secret keys: For both Test and Live, we provide a public key and a secret key. The secret key is like your ID number – unique to you and should only be visible under certain circumstances. Like a password, your secret key must never be revealed to anyone and should be securely stored on your server.
❗ Important: Always copy and paste your API keys – don’t retype them.
→ SSL certification
🔒 An SSL certificate is a digital security certificate that encrypts the information shared between a website and its visitors. It helps keep data like card details and personal information private and secure.
The SSL (or TSL which is the successor to SSL) for your website must be enabled for the payment module to load. If you need help troubleshooting your SSL/TSL certification, please select your platform below.
✨ Is your SSL certificate valid?
Here’s how you can check:
Enter your website URL in the search box.
When the search results appear, check that the certificate is valid and that the certificate chain isn’t broken – see example of a valid SSL certificate below.
Please note: If you need help validating your SSL certificate, please contact the service provider that supplied your certificate.
→ Currency settings
Your website’s currency must be in South African Rands (ZAR) for transactions to be activated with Yoco. To change your currency settings so that your customers are being charged in ZAR, select your platform below.
💶 Want to give your international customers an idea of what they'll be paying? Select the relevant platform below to find out how to add a currency converter to your website.
Plugin suspended due to missing installation ID
If you’re seeing this error message on your WooCommerce website, head to Yoco Payments > Settings and select Save changes. Then follow these steps to confirm that your secret keys are correct:
Check that your website is loading without prompting you to enter a username and password. The plugin won’t install if your website requires user authentication before it loads, for example if it’s still under development. Try to remove the need for user authentication, then reinstall the plugin.
If your website loads without prompting you to enter a username and password:
Go to WooCommerce > Installed Plugins > Yoco Payments > Settings
Erase the secret keys values from the settings.
Copy the secret keys values from the Yoco Web App and paste them into the WooCommerce Admin in the plugin settings.
Select the Enable logging checkbox.
Select the Save changes button.
Reinstall the plugin. If this doesn’t work, click here to validate your SSL certificate.
❗Important: Always copy and paste your API keys – don’t retype them.
Test transaction: Error messages
✨ Please note: Test mode isn’t necessary for Shopify as API keys are automatically part of your integration.
‘3D Secure authentication has failed. Please try again.’ OR ‘There was a problem preparing your payment request. Please try again.’
Check that you’re using a test card, not a real card. The test card is displayed below your Live and Test keys in the Payment Gateway tile/widget in the Yoco App (mobile or web).
If you’ve confirmed that you’re using a test card, but the problem persists, try the following:
Make sure that the plugin is in Test mode.
Check that you’re using the correct Private and Secret test keys in the correct fields, and that there are no spaces.
For more information, view our Developers' Guide.
❗Important: Always copy and paste your API keys – don’t retype them.
Live transaction: Error messages
→ Payment Unavailable: 'This business can’t take online payments yet'
This message means your business can’t accept online payments right now because we’re still completing some required checks in the background.
In most cases, you don’t need to do anything. Once the checks are done, online payments will be enabled automatically.
If this message is still showing after 24–48 hours, contact support so we can help.
→ 'There was a problem preparing your payment request. Please try again.’
Confirm that the plugin is in Live mode.
Make sure you’re using the correct Private and Secret Live keys in the correct fields.
Check that there are no spaces between the characters.
For more information, view our Developers' Guide.
→ ‘Something went wrong, please contact support.’
Check that the transaction total exceeds the minimum payment amount of R2,00.
→ ‘3D Secure authentication has failed. Please try again.’
Make sure that the transaction hasn’t been declined – payments are mostly declined because:
a. The customer entered their card details incorrectly.
b. The customer’s internet connection was interrupted while the payment was being processed.
c. The customer’s card isn’t accepted by Yoco.
d. The bank declined the payment because:
The customer has insufficient funds.
The customer failed to complete 3D Secure authentication.
The bank does not carry out 3D Secure authentication.
The bank does not allow the customer to do online payments.
Banking system challenges or downtime.
The transaction total is less that the minimum payment amount (R2,00).
e. The Yoco system is down. This is very unlikely to happen and you will have been notified via email and in-App or on-device pop-up messages.
💡 Please note: Capitec cards have shown a higher rate of 3D Secure authentication failures compared to other banks.
✨ Click here to find out more about troubleshooting card transactions.
→ My customer paid online, and their card was successfully charged. But, they received an error message and the order says ‘incomplete’.
This error can occur when your connection to the Yoco servers is interrupted, or your server fails to respond in time.
Log in to the Yoco Web App.
Go to the Sales tab.
Select the Sales history tile/widget.
Find the transaction in your Sales history, then check the Status column to see whether the transaction was approved.
If the transaction was successful, manually mark the order as paid on your website.
If the transaction wasn't successful, but your customer insists that it went through, ask them to email proof of payment to you, then send it to us via our in-app chat and we’ll investigate.
→ The payment pop-up doesn’t display after entering the amount.
Try entering the amount in cents, rather than as a decimal value. This typically means adding 00 after the amount. For example, enter 200 to charge R2 or 5000 to charge R50.
Need more help?
Our Support Team is waiting to assist you with your Yoco Gateway query. Before you reach out to them via our in-app chat, please complete these tasks so they can get you back on track as quickly as possible.
Create a new user profile with admin privileges.
This will allow our Support Team to enable/disable plugins and modify any settings that may be interfering with the Yoco App and your ability to accept payments. Save the login details to share with us. This profile can be deleted once the issue has been resolved. Click the relevant link for instructions: WooCommerce | Wix | Shopify
Make a list of the plugins enabled on your site.
This will allow our Support Team to identify any plugins that may be clashing with one another.
Enable error debugging.
Do this by connecting to your site via SFTP, downloading the config.php file to edit, and updating it. Remember: Always make a backup of this file before continuing. Click the relevant link for instructions: WooCommerce | Wix | Shopstar | Shopify | Custom
Export or save error logs from the date you first noticed the issue.
You’ll find your error logs in the Logs folder of your website. Once you've exported them, attach them to your support request.
Helpful links
WooCommerce
Wix
Shopstar