Yoco Gateway Plugin help

When it comes to troubleshooting with the Yoco Online Payment Gateway, it’s important to first do some fundamental checks on your setup, because without proper configuration, your plugin won’t be able to work.

Plugin not displaying on your website?

Key Trouble Checks:

1. API Keys:

Your Test and Live Keys need to be configured properly - are you sure you’re using the right API keys? Follow the steps here, or keep reading to make sure you’re on the right track.

This does not apply for Shopify plugin users. Shopify handles all API integration themselves, so it’s automatically part of your installation.

Test keys are for safely testing out how the Yoco Gateway works on your website. Test keys can only be used with the test card details, also provided in your Portal.

Live keys are for when all your testing is complete, and 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. You can think of the public key almost like your ID number. It's only visible to others under certain circumstances. But the secret key is like a password that no-one else should ever see.

Screenshot 2022-06-10 at 12.41.09 (2).png

2. SSL Certification:

“An SSL certificate is a digital certificate that authenticates a website's identity and enables an encrypted connection. SSL stands for Secure Sockets Layer, a security protocol that creates an encrypted link between a web server and a web browser.’’ — learn more here.

Your website’s SSL (or TSL) needs to be enabled, otherwise the payment module won’t be able to load. Need help? Choose your platform for their guide: WooCommerce | Wix | Shopstar | Shopify | Custom

3. Currency Settings:

Your website’s currency needs to be in ZAR, otherwise transactions won’t be able to be activated with Yoco. So, you’ll need to make sure your Yoco shop currency is set to South African Rands, and that you charge your customers in ZAR. It’s easy to change your currency settings, just pick your guide:WooCommerce | Wix | Shopstar | Shopify | Custom

You may also want to give your international customers an idea of what they'll pay, by giving them access to a currency conversion estimating tool on your website too. WooCommerce | Wix | Shopstar | Shopify | Custom

4. Subscriptions:

Subscriptions are currently only available on our WooCommerce plugin, and must be properly configured there too. Otherwise, using subscription products will deactivate the payment plugin.

Struggling with Test Mode?

Skip this step if you’re using Shopify — API Keys are automatically part of the integration.

Test transaction says, ‘3D Secure authentication has failed. Please try again.’ or ‘There was a problem preparing your payment request. Please try again.’

Make sure you’re using a test card, not a real card. This is displayed right below your Live and Test keys, and looks like this:

If you’re sure that it’s the test card that’s failing, make sure that the plugin is in Test Mode and that you’re using the correct Private and Secret Test Keys in the correct fields, and that there are no spaces. For more details, check out our developer guide here.

Online payment errors and issues

Yoco Gateway

My customer is getting a message that says, ‘There was a problem preparing your payment request. Please try again.’

Make sure that the plugin is in Live Mode and that you’re using the correct Private and Secret Live Keys in the correct fields, and that there are no spaces. For more details, check out our developer guide here.

My customer paid online, and their card was successfully charged. But, they got an error message (even though the transaction went through) and on my Portal, the order says ‘incomplete’.

From time to time your website may not have enough processing power to process a transaction successfully.

Log into the Yoco Portal here: you'll be able to see every transaction processed through your Yoco profile, by date.
Check to see if the transaction did actually succeed — see more here.
If it was successful, you can manually mark the order as paid on your website.
If it wasn't successful, but your customer insists: they'll please need to email Yoco a copy of their bank statement (showing the charge) so we can get to the bottom of this urgently ([email protected]).

All Online Payments

My customer is getting a message that says, “Something went wrong, please contact support.”

Sometimes this error message gets displayed when the transaction is smaller than the minimum transaction size amount of R2,00.

My customer is getting a message that says, ‘3D Secure authentication has failed. Please try again.’

First, make sure that the transaction wasn’t declined: most times, it’s a problem on the customer’s side (either banking or user error) but here are some of the most common reasons why payments get declined:

The customer made a mistake when entering their card details.
The customer had an interrupted internet connection while processing their payment (read more here).
The customer’s card isn’t one of those accepted by Yoco: can accept all MasterCard and Visa debit and credit cards. This includes international and AMEX cards, swipe cards, chip and PIN, and SASSA cards. Issued from any bank.

Unfortunately, we don't currently accept Fleet / RCS / Diners / Petrol cards.
Note: We support Capitec cards but they do have more 3DS failures than other issuing banks. Get the full list here.
The customer’s bank declined the transactions because:
- Insufficient funds
- Failure to do 3D Secure authentication
- Bank does not do 3D Secure authentication
- Bank does not allow the customer to do online payments
- Challenges or downtime on the banking system side
Our platform could be down (highly unlikely) in which case, you’ll have been notified via email as well as in-App or on-device pop-up messages.

Read more about understanding failed transactions here.

Finally, make sure the transaction amount is at least R2,00!

"The payment pop-up isn't displaying when I finish entering the amount."

Make sure to enter the amount in cents, not decimal value - in most cases, this means you need to add "00" at the end of the amount. For example, to charge R2 you must enter "200"; to charge R50 you must enter "5000".

Payment status messages (and what they mean)

Pending: This means the transaction hasn’t been made yet or is still being processed – it’s still too soon to tell whether it’ll be approved or not. If your customer says they’ve paid, but it’s ‘pending’ on your end, ask your customer to send through proof of payment so we can investigate what happened.
Aborted: This means that the transaction failed, because it was cancelled during the payment process.
Approved: This means that the transaction was successful, and should now be reflected in your Sales History.

Still Struggling with Yoco Gateway? Get the best Support:

If you still haven’t managed to resolve things by troubleshooting the above steps, it’s definitely best to contact us, and get a Yoco human’s assistance. To help us get stuck in straight away, and fix things as fast as possible, we recommend following these steps in preparation for your Support reach out:

Create an Admin profile for Yoco Support: create a new user with admin privileges on your website. This will allow us to enable/disable plugins and modify settings that may be interfering with the Yoco App and your ability to accept payments. Please save the login details so you can share them with us. This profile can be deleted once the issue has been resolved. Pick your integration platform for some help on how to do this: WooCommerce | Wix | Shopstar | Shopify
Make a list of all the plugins currently enabled on your site: Some plugins can cause conflicts amongst each-other, so we’ll help look into that together.
Have you enabled error debugging? Make sure you’ve enabled error debugging, by connecting to your site via SFTP, downloading the config.php file to edit, and updating it. Remember to always make a backup of this file first, before continuing. WooCommerce | Wix | Shopstar | Shopify | Custom
Export or save error logs from the date you first noticed the issue. Access the "logs" folder of your website, and save the relevant logs for attaching to your support request.