Skip to content

Commit

Permalink
Merge pull request #1422 from TChukwuleta/seo_improvement
Browse files Browse the repository at this point in the history 
open cart doc improvement
  • Loading branch information
@pavlenex
pavlenex authored Nov 27, 2024
2 parents 8856dea + 83fd38c commit 8ef500a
Showing 1 changed file with 66 additions and 34 deletions.
100 changes: 66 additions & 34 deletions docs/OpenCart.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,39 @@ tags:
- eCommerce
---

# OpenCart integration
# Accept Bitcoin payments in OpenCart

[BTCPay Server](https://btcpayserver.org/) is a free and open-source Bitcoin payment processor. It allows you receive payments directly into your wallet with no fees, or middleman.

If you run an OpenCart store, expand your market reach today without any additional marketing cost by integrating it with BTCPay Server to offer Bitcoin as a payment option.


## Benefits of using BTCPay for OpenCart

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

2. **Zero Fees:** BTCPay Server is free. That’s right—no transaction fees, no processing fees, ever.

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

4. **Lightning Network Integration:** Enjoy instant, low-cost payments and payouts.

5. **Easy data exports:** Easily manage your financial reports with CSV export options.

6. **Versatile Plugin System:** Extend BTCPay’s functionality with a flexible plugin system tailored to your needs.

7. **Point-of-Sale Integration:** Accept Bitcoin in physical stores with POS integration.

8. **Multilingual Ready:** Serve your global audience in a language they understand

9. **Self-Hosted Infrastructure:** Choose self-hosting for full control or a third-party host for convenience. Both provide the complete BTCPay experience.

10. **Community-Driven Support:** Get help and advice from a dedicated community ([Mattermost](http://chat.btcpayserver.org/) or [Telegram](https://t.me/btcpayserver)).

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

## Requirements

Please ensure that you meet the following requirements before installing this extension.
Ensure that you meet the following requirements before installing this extension.

- PHP version >= 7.4 for OpenCart 3; PHP >= 8.1 for OpenCart 4
- The curl, gd, intl, json, and mbstring PHP extensions are available
Expand All @@ -26,55 +52,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 +123,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 +163,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 8ef500a

Please sign in to comment.