What you need to do to add a payment gateway to OpenCart

Adding a payment gateway to OpenCart means installing and configuring a module that lets your store accept payments through a specific processor—Stripe, PayPal, Square, or another service. OpenCart stores the gateway module in a folder, then you enable it through the admin panel and enter your account credentials so transactions can flow from your checkout to the processor's servers.

The process has three parts: getting the module files (either built into OpenCart or downloaded separately), uploading them to your server if needed, and configuring the gateway with your merchant account details. Most gateways take 10 to 30 minutes to set up once you have your merchant account open and your API keys or credentials ready.

Key Takeaways

  • OpenCart comes with several payment gateways pre-installed (PayPal, Authorize.net, 2Checkout); you only need to enable and configure them.
  • Third-party gateways like Stripe or Square require you to download the module files, upload them to your server, then enable and configure them in the admin panel.
  • Every gateway needs your merchant account credentials—API keys, secret keys, or login details—which you get from the payment processor's dashboard.
  • Test mode lets you process fake transactions before going live; always test your gateway before customers use it.
  • Payment gateway modules live in admin/controller/payment, admin/model/payment, and catalog/controller/payment folders on your server.

Finding and downloading the payment gateway module

Check whether your gateway is already built into OpenCart. Log into your admin panel, go to Extensions > Payments, and scroll through the list. If you see your processor (PayPal, Authorize.net, 2Checkout, Worldpay, or others), it is already installed and you can skip to the configuration step.

If your gateway is not listed, download the module from the OpenCart Marketplace or directly from the payment processor's website. The OpenCart Marketplace (at marketplace.opencart.com) has modules for Stripe, Square, Amazon Pay, Google Pay, and many regional processors. Download the file as a compressed folder (usually .zip or .ocmod.zip format).

Some payment processors provide their own OpenCart modules on their developer portals. Stripe, for example, has a module on their GitHub repository. Square, PayPal, and Authorize.net also publish modules directly. Check the processor's documentation first—their module may have features or support that a third-party version does not.

Uploading the module files to your server

If the module file ends in .ocmod.zip, OpenCart can install it directly through the admin panel without manual upload. Go to Extensions > Installer, click Upload, select the .ocmod.zip file, and OpenCart unpacks it into the correct folders automatically.

If the file is a standard .zip (not .ocmod.zip), extract it on your computer first. You will see folders named admin, catalog, and sometimes system. Open your server via FTP or your hosting control panel's file manager, navigate to your OpenCart root directory, and upload these folders. The files merge with your existing folder structure—do not replace the entire folder, just add the new files inside.

After upload, clear your OpenCart cache. In the admin panel, go to System > Cache and click Refresh. This tells OpenCart to recognize the new module files.

Enabling the payment gateway in your admin panel

Go to Extensions > Payments in your OpenCart admin. Find your gateway in the list and click Install (or Enable if it is already installed). The button changes to show the gateway is now active.

Click Edit next to the gateway name. This opens the configuration page where you enter your merchant account details. Every gateway has different fields, but most ask for:

  • API Key or Merchant ID—your unique identifier at the payment processor
  • Secret Key or API Secret—a private key that authenticates requests from your store
  • Test/Live Mode toggle—a switch to use test credentials or live credentials
  • Transaction Type—whether to authorize only (hold the funds) or authorize and capture (take the funds immediately)
  • Order Status—what status a pending or completed payment should set on the order
  • Sort Order—where this gateway appears in the checkout payment list
  • Geo Zone—which countries or regions can use this gateway (optional)

Get your API keys from your payment processor's merchant dashboard. Log into Stripe, PayPal, Square, or whichever service you use, find the API or Developers section, and copy your test keys first. Paste them into the corresponding fields in OpenCart, then save.

Testing the payment gateway before going live

Leave the gateway in test mode and place a test order from your store's front end. Go through checkout, select the payment gateway, and enter test card numbers provided by your processor. Stripe's test card is 4242 4242 4242 4242; PayPal has a sandbox environment with test accounts; Square provides test card numbers in their documentation.

Complete the transaction and check two places: your OpenCart order history (go to Sales > Orders and look for the test order) and your payment processor's dashboard (log in and check your test transactions). Both should show the transaction went through. If either one is missing or shows an error, check your API keys for typos and make sure test mode is enabled.

Test a failed payment too. Use an expired card (04/20) or a card number that your processor marks as declined. The checkout should reject it and show an error message. This confirms your error handling is working.

Switching to live mode and going live

Once testing passes, go back to Extensions > Payments, click Edit on your gateway, and replace the test API keys with your live keys from your merchant dashboard. Toggle the mode from Test to Live (or disable test mode, depending on how the module is built). Save the changes.

Your store now processes real transactions. Place a small real order to confirm the live keys work, then monitor your payment processor's dashboard for the next few days to make sure transactions are flowing correctly.

Keep your API keys private. Never share them in emails, paste them into public forums, or commit them to version control. If you suspect a key has been exposed, regenerate it immediately in your merchant dashboard and update it in OpenCart.

Troubleshooting common payment gateway problems

The gateway does not appear in the payment list at checkout. Check that it is installed and enabled in Extensions > Payments. If it is enabled but still missing, clear your cache at System > Cache. If you set a Geo Zone restriction, make sure your test address matches that zone. Some gateways also require a minimum order total—check the module settings.

Transactions are declined or return an error. Verify your API keys are correct and copied exactly (no extra spaces). Make sure you are using test keys in test mode and live keys in live mode. Check your payment processor's logs—they usually show the exact reason for the decline (invalid key, account not active, IP address not whitelisted, etc.). Some processors require you to whitelist your store's IP address in their security settings.

The order status does not update after payment. Check the Order Status setting in the gateway configuration. Make sure you have set a status for successful payments. Some gateways also send a confirmation back to your store (called an IPN or webhook); if this is not configured, your store may not know the payment succeeded. Check your processor's documentation for webhook setup and enter your store's URL in their dashboard.

Customers see a blank page or error after clicking Pay Now. This usually means the module files were not uploaded correctly or the API keys are invalid. Check your server error logs (usually in a logs folder in your hosting control panel) for PHP errors. Re-upload the module files and verify the folder structure matches what the module documentation specifies.

Frequently Asked Questions

Can I use more than one payment gateway at the same time?

Yes. Install and enable multiple gateways in Extensions > Payments, and customers will see all of them as options at checkout. Set the Sort Order for each gateway to control which appears first. This is useful if you want to offer Stripe and PayPal, or regional processors alongside international ones.

What is the difference between test mode and live mode?

Test mode uses fake credentials and test card numbers; transactions do not move real money and do not appear in your actual merchant account. Live mode uses your real credentials and processes real payments. Always test in test mode first, then switch to live mode only after confirming transactions work end-to-end.

Do I need a merchant account before installing a payment gateway?

Yes. You must sign up with the payment processor (Stripe, PayPal, Square, etc.) and receive your API keys before you can configure the gateway in OpenCart. The gateway module itself is just the connection; it cannot process payments without an active merchant account at the processor.

What if my payment processor is not in the OpenCart Marketplace?

Check the processor's website for an OpenCart module or plugin. If they do not have one, contact their support team—they may provide custom integration instructions or a developer can build a module for you. Some smaller processors only support payment links or hosted checkout pages, which you can add to OpenCart using custom code or a general payment link module.

How do I know if a transaction succeeded?

Check your OpenCart order history and your payment processor's dashboard. Both should show the transaction. If one shows it and the other does not, your webhook or IPN may not be configured. Contact your processor's support team with the transaction ID to investigate.