Skip to content

Commit

Permalink
open cart doc improvement
Browse files Browse the repository at this point in the history
  • Loading branch information
@TChukwuleta
TChukwuleta committed Aug 29, 2024
1 parent 0116901 commit 9c1d9d6
Showing 1 changed file with 77 additions and 33 deletions.
110 changes: 77 additions & 33 deletions docs/OpenCart.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,47 @@ tags:
- eCommerce
---

# OpenCart integration
# BTCPay Server Integration with OpenCart: A Complete Guide

[BTCPay Server](https://btcpayserver.org/) is a free and open-source cryptocurrency payment processor which allows you to receive payments in Bitcoin and altcoins directly, with no fees, transaction cost or a middleman.

If you run an OpenCart store, integrate your store today with BTCPay Server to help expand your payment options, attract crypto-savvy customers, without any charges.

This guide covers the integration process for both OpenCart 3 and OpenCart 4, helping you set up BTCPay Server quickly and efficiently.


## Why Choose BTCPay Server: Unmatched Benefits for Your Payment Processing

BTCPay Server is a non-custodial invoicing system that ensures complete control over your payments by eliminating third-party involvement. With the BTCPay Server OpenCart extension, payments are sent directly to your wallet, enhancing both privacy and security.

BTCPay Server can be deployed as a self-hosted solution on your own server, or you can opt for a third-party host. The self-hosted option not only allows you to manage an unlimited number of stores and leverage the Lightning Network, but also gives you the flexibility to act as a payment processor for others.

Other benefits of Using BTCPay Server with OpenCart include:

1. **Zero Fees:** BTCPay Server offers a truly fee-free payment gateway. That’s right—no transaction fees, no processing fees, ever.

2. **Direct Payments, No Middlemen:** Receive your funds directly in your wallet without the need for intermediaries or tedious KYC procedures. Experience the freedom of peer-to-peer transactions.

3. **Fully Automated System:** Let BTCPay handle everything for you—payments, invoice management, and refunds—automatically.

4. **Bitcoin QR Code at Checkout:** Enhance your customer’s experience with a simple and secure payment process by displaying a Bitcoin QR code at checkout.

5. **Self-Hosted Infrastructure:** Maintain full control over your payment gateway with a self-hosted solution, or opt for a third-party host if you prefer.

6. **Lightning Network Integration:** Enjoy instant, low-cost payments and payouts with built-in support for the Lightning Network.

7. **Easy CSV Exports:** Simplify your financial management with easy-to-use CSV export options.

8. **Versatile Plugin System:** Customize and extend BTCPay’s functionality with a flexible plugin system tailored to your needs.

9. **Point-of-Sale Integration:** Seamlessly accept Bitcoin and altcoin payments in your physical stores with our POS integration.

10. **Multilingual Ready:** Serve a global audience right out of the box with multilingual support.

11. **Altcoin Support:** BTCPay Server also supports a wide range of altcoins, providing flexibility for you and your customers.

12. **Community-Driven Support:** Get help and advice from a dedicated community via Mattermost or Telegram.

This document explains how **to integrate BTCPay Server into your OpenCart store**. Supported are OpenCart 3 and 4.

## Requirements

Expand All @@ -26,55 +64,55 @@ Please ensure that you meet the following requirements before installing this ex
The instructions are based on OpenCart 3, but the UI and steps are almost identical to OpenCart 4. Therefore we have no separate instructions.
:::

## 1. Install BTCPay extension
## Step-by-Step Guide to Install the BTCPay Extension for OpenCart
### 1. Install BTCPay extension

There are three ways to **download the BTCPay for OpenCart extension**:

- Via the Admin Dashboard (recommended, see below)
- Via the Admin Dashboard (recommended)
- [OpenCart Marketplace](https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=44269)
- [GitHub Repository](https://github.com/btcpayserver/opencart)

### 1.1 Install the extension from OpenCart admin dashboard
#### 1.1 Install the extension from OpenCart admin dashboard

Note: work in progress, extension undergoing review atm.
Note: The extension is currently undergoing review and will be available soon.

### 1.2 Download and install the extension from Marketplace or GitHub
#### 1.2 Download and install the extension from Marketplace or GitHub

1. Download the latest BTCPay extension from [Github](https://github.com/btcpayserver/opencart/releases) or [Marketplace](https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=44269)
2. Menu: Extensions -> Install
1. Download the latest BTCPay extension from the [Marketplace](https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=44269) or [Github](https://github.com/btcpayserver/opencart/releases)
2. Navigate to Menu: Extensions -> Install
3. Click the button [Upload] and upload the downloaded `btcpay.ocmod.zip`
After uploading, you should see a notice "Success: You have modified extensions! "
After the upload completes, you should see a notification saying, "Success: You have modified extensions!"

![BTCPay OpenCart: Extension installation upload](./img/opencart/oc3--01--upload-zip.png)

### 1.3 Install the extension
#### 1.3 Complete the Extension Installation

1. Menu: Extensions -> Extensions
2. On the "Choose extension type" dropdown, select "Payment".
3. On the "Action" column, click the green install button.
4. You will see a notification " Success: You have modified payments!"
1. Go to Menu: Extensions -> Extensions
2. In the "Choose extension type" dropdown menu, select Payment.
3. Find the BTCPay extension in the list and click the green Install button in the "Action" column.
4. You will see a notification saying: "Success: You have modified payments!"

![BTCPay OpenCart: Install extension](./img/opencart/oc3--02--install-btcpay.png)

## 2. Connecting OpenCart and BTCPay Server
### 2. Connecting OpenCart and BTCPay Server

Please make sure to have a BTCPay Server instance setup as described in the [requirements](#requirements) above.
Before proceeding, ensure you have a BTCPay Server instance set up as described in the [requirements section](#requirements).

BTCPay for OpenCart extension is a **bridge between your BTCPay Server (payment processor) and your e-commerce store**.
No matter if you're using a self-hosted or third-party solution, the connection process is identical.
The BTCPay for OpenCart extension acts as a **bridge between your BTCPay Server (payment processor) and your e-commerce store**. Whether you're using a self-hosted or a third-party solution, the connection process remains the same.

### 2.1 Configure BTCPay Server extension in OpenCart
#### 2.1 Configure BTCPay Server extension in OpenCart

1. Menu: Extensions -> Extensions
2. Click the blue edit button
1. In the OpenCart panel, navigate to Extensions -> Extensions.
2. Find the BTCPay extension in the list and click the blue Edit button.
![BTCPay OpenCart: Add new payment method](./img/opencart/oc3--03--configure-btcpay.png)
3. Configure BTCPay extension. ![BTCPay OpenCart: Payment method details](./img/opencart/oc3--04--configure-btcpay-page.png)
4. On the field "Payment Method Enabled" set it to `Enabled`
5. On field "BTCPay Server URL" set it to the URL where your BTCPay Server instance is reachable on the internet e.g. `https://mainnet.demo.btcpayserver.org/`. You can find information on how to deploy your BTCPay Server instance in the [requirements section above](#requirements)
4. Set the "Payment Method Enabled" field to Enabled.
5. In the "BTCPay Server URL" field, enter the URL where your BTCPay Server instance is accessible, e.g., https://mainnet.demo.btcpayserver.org/. Instructions for deploying your BTCPay Server instance can be found in [requirements section above](#requirements)

Before you can continue, you need to create the API key for your user and store, as described in the next section. Keep this browser tab open, as we will come back shortly.

### 2.2 Create an API key and configure permissions
#### 2.2 Create an API key and configure permissions

On your BTCPay Server instance:

Expand All @@ -97,21 +135,27 @@ On your BTCPay Server instance:
10. Back on _OpenCart BTCPay settings_ form make sure **BTPCay Server URL**, **API Key** and **Store ID** are set and click **[Save]** button (on the top right)
![BTCPay OpenCart: Save OpenCart Settings form](./img/opencart/oc3--10--save-settings.png)

You should get back to the Extensions overview page and see the notification "BTCPay Server Payment details have been successfully updated.". If not, ensure your URL, API Key and Store ID are correct.

Return to the Extensions overview page, you should see a notification that says "BTCPay Server Payment details have been successfully updated.". If not, double-check that your URL, API Key, and Store ID are correctly entered.
![BTCPay OpenCart: Save OpenCart Settings form](./img/opencart/oc3--11--save-settings-success.png)

On successfully saving, the BTCPay extension automatically creates a webhook so OpenCart can get notified when payments settle or fail. To double check it was successful. You can do that by editing the BTCPay extension settings again if you see the "Webhook Data" field filled out like this:
On successfully saving, the BTCPay extension automatically creates a webhook to notify OpenCart when payments are settled or failed. To double check it was successful. You can do that by editing the BTCPay extension settings again if you see the "Webhook Data" field filled out like this:
![BTCPay OpenCart: Save OpenCart Settings form](./img/opencart/oc3--12--webhook-success.png)

As you can see on the BTCPay extension settings, you can customize the order statuses depending on the [invoice statuses](https://docs.btcpayserver.org/Invoices/#invoice-statuses) and other common settings. The defaults should be a good starting point but feel free to adjust them to your use case.
As you can see on the BTCPay extension settings, you can customize the order statuses depending on the [invoice statuses](https://docs.btcpayserver.org/Invoices/#invoice-statuses) and other common settings. The defaults should be a good starting point but feel free to adjust them to your specific needs.


### 3. Test the checkout

## 3. Test the checkout
Now everything is set up; it's time to perform a test transaction:

Everything is ready to go now. Make a small test purchase and make sure the order status gets updated according to the BTCPay invoice status. On the BTCPay Server invoice details, you can see if the webhook events were successful.
Make a Test Purchase: Place a small order through your OpenCart store to ensure the checkout process works as expected.
Verify Order Status: Check that the order status in OpenCart updates according to the corresponding BTCPay invoice status.
Review Webhook Events: In the BTCPay Server invoice details, confirm that the webhook events were successful.

## Troubleshooting
### Troubleshooting

### Enable debug mode
#### Enable debug mode

If you have an error during checkout, you can enable the debugging mode on the BTCPay extension settings. Menu: Go to "Extensions -> extensions" select "Payments" on the "Choose Extension Type" dropdown and edit BTCPay Server extension.

Expand All @@ -131,7 +175,7 @@ You can now find the debug output in the `error log` in the menu "System -> Main

- Another reason could be that you use a legacy API key. The legacy API keys are located in store settings -> Access Tokens. But you need to create an account API key located in Account -> Manage Account -> tab "API Keys". See section [2.2 Create an API key and configure permissions](#22-create-an-api-key-and-configure-permissions).

## The order states do not update, although the invoice has been paid.
### The order states do not update, although the invoice has been paid.

Please check your invoice details to see if there were any errors on sending the webhook request. Some hosting providers, firewall setups, or security extensions may block POST requests to your site, which leads to an HTTP status of "403 forbidden".

Expand Down

0 comments on commit 9c1d9d6

Please sign in to comment.