How to run hyperswitch in Docker Container and Compose

A payment Switch can be defined as a tool to facilitate communication between different payment service providers. It provides a merchant-driven rules-based authorization and switching solution. This is achieved by dynamically routing payment transactions between multiple acquirers and Payment Service Providers. It normally sits at the core of payment processing where it can dynamically acquire, route, switch, authenticate, and authorize transactions across multiple payment channels.

Below is a diagram to illustrate the switching process

HyperSwitch is an open-source Financial Switch, that can be used to make payments fast and reliable. It makes it possible to connect with multiple payment processors with a single API integration. After the integration, you can easily add new payment processors and route traffic effortlessly.

HyperSwitch is preferred due to the following features and benefits:

• It improves success rates with auto-retries
• Reduces processing fees through smart routing
• Reduces dependency on a single processor like Stripe or Braintree
• Reduces Dev efforts by 90% in adding & maintaining integrations
• Helps embrace diversity in payments
• Increase business reach with local payment methods
• Customize your payment flow with 100% visibility and control
• Wire-compatible with top processors like Stripe making it easy to integrate.

When installing HyperSwitch, you have two options:

• Install it in a Sandbox environment which is fast and easy to start. No code or setup is required in your system.
• Install it on the local system where configs are needed. This is suitable when you want to customize the core offering. There are two options to set up HyperSwitch on your system:
  • Use Docker Compose
  • Set up a Rust environment and other dependencies on your system

Today we will learn how to run hyperswitch in Docker Container with Docker Compose.

1. Install Docker and Docker-Compose

We’ll begin by installing both the Docker Engine and Docker-Compose. The below guide provides all the steps to install the Docker Engine on Linux:

• How To Install Docker CE on Linux Systems

Once installed, ensure the daemon is started and enabled.

sudo systemctl start docker && sudo systemctl enable docker

You also need to add the system user to the docker group.

sudo usermod -aG docker $USER
newgrp docker

Now install Docker-compose using the below guide:

• How To Install Docker Compose on Linux

2. Provision the HyperSwitch Container

To obtain the required manifest, we will clone the GitHub repository as shown:

git clone https://github.com/juspay/hyperswitch
cd hyperswitch

You can now make the desired configurations to the docker-compose.yaml file:

vim docker-compose.yml

For this guide, we will keep the defaults, The configuration files are stored under the config directory. There are several configs here such as the docker_compose.toml, Prometheus.yaml, redis.conf e.t..c.

3. Run hyperswitch Using Docker Compose

We can now start all the containers using the YAML file. This can be achieved using the command:

docker compose up -d

Verify if all the containers are up:

$ docker ps
CONTAINER ID   IMAGE                                       COMMAND                  CREATED         STATUS                   PORTS                                         NAMES
95f206abc04c   juspaydotin/hyperswitch-router:standalone   "/local/bin/router -…"   5 minutes ago   Up 3 minutes (healthy)   0.0.0.0:8080->8080/tcp, :::8080->8080/tcp     hyperswitch-hyperswitch-server-1
62f81578460f   redis:7                                     "docker-entrypoint.s…"   5 minutes ago   Up 5 minutes             0.0.0.0:32769->6379/tcp, :::32769->6379/tcp   hyperswitch-redis-standalone-1
54859421daa0   postgres:latest                             "docker-entrypoint.s…"   5 minutes ago   Up 5 minutes             0.0.0.0:5432->5432/tcp, :::5432->5432/tcp     hyperswitch-pg-1

Once complete, you can check the health of the server with the command:

$ curl --head --request GET 'http://localhost:8080/health'
HTTP/1.1 200 OK
content-length: 14
via: HyperSwitch
access-control-allow-credentials: true
vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers
access-control-expose-headers: strict-transport-security, via, x-request-id
strict-transport-security: max-age=31536000
x-request-id: 018cbc59-42c0-755d-a57b-a447f7afc221
date: Sat, 30 Dec 2023 20:10:15 GMT

The above output shows that everything is okay.

4. Test using Hyperswitch Control Centre

We can test the setup by running a merchant account. To achieve this, you can either use the Hyperswitch Control Centre or Postman

For this guide, we will locally deploy and use the Hyperswitch Control Centre.

First, ensure that NodeJS and NPM are installed. Here, we will use NodeJS 20 which can be installed with the below aid.

• Install and Use Node.js 20 LTS on Rocky 8 / AlmaLinux 8
• How To Install Node.js 20 LTS on Ubuntu

Verify the installations with the commands:

$ node -v
v20.10.0

$ npm -v
10.2.3

a. Set up Self-Hosted Hyperloader.js and Card vault

We need to have the self-hosted Hyperloader, the engine behind our checkout page. It ensures that the Hyperswitch server displays the checkout and card details.

First, we will need to export a few variables:

###This is the host name of the web service where Hyperloader.js will be hosted on Nginx/Apache. Do not add / at the end
export envSdkUrl=http://your_IP_address OR domain-name 

###This is the host name of the Hyperswitch App. do not add / at the end
export envBackendUrl=http://your_IP_Address:8080 

Once the variables have been exported, clone the repo:

git clone --branch v0.16.7 https://github.com/juspay/hyperswitch-web
cd hyperswitch-web

Then install all the dependencies and build the project:

npm install
npm run re:build
envSdkUrl=$envSdkUrl envBackendUrl=$envBackendUrl npm run build:integ

After this, the /dist/integ folder will be created. This folder will contain HyperLoader.js along with many other files.

Install Nginx web server to help use server the files:

##On Debian/Ubuntu
sudo apt install nginx -y

##On Rhel/Rocky/Alma Linux
sudo yum install nginx -y

Copy the contents of /dist/integ to the web root directory at /0.16.7/v0.

sudo mkdir -p /var/www/html/0.16.7/v0/
sudo cp -r dist/integ/* /var/www/html/0.16.7/v0/

Now create the config file to serve the HyperLoader.js:

sudo vim /etc/nginx/conf.d/hyperswitch.conf

In the file, add these lines and replace the server_name with the value provided at the envSdkUrl

server {
   listen 80;
    server_name hyperswitch.test.com;

    location /0.16.7/v0/ {
        alias /var/www/html/0.16.7/v0/;
        index index.html;
    }
        error_page 404 /404.html;
            location = /40x.html {
        }

        error_page 500 502 503 504 /50x.html;
            location = /50x.html {
        }
    # Add other Nginx configurations as needed
}

Save the file and restart Nginx:

sudo systemctl restart nginx

Verify that you can access the HyperLoader.js from the web. For example in my case, the URL will be http://hyperswitch.test.com/0.16.7/v0/HyperLoader.js

b. Setup Hyperswitch Control Centre

Now clone the Hyperswitch Control Centre. git repo:

cd
git clone https://github.com/juspay/hyperswitch-control-center.git

Navigate to the directory:

 cd hyperswitch-control-center

Now install all the required dependencies:

npm install --force

The next thing is to update your variables and provide your Hyperswitch base URL.

$ vim .env
apiBaseUrl = your-backend-url
sdkBaseUrl = your-sdk-url

Replace:

• apiBaseUrl with the URL of your Hyperswitch server for example http://192.168.200.51:8080
• sdkBaseUrl with the URL to your HyperLoader.js. For example http://hyperswitch.test.com/0.16.7/v0/HyperLoader.js

The proceed and compile the code:

npm run re:start

Sample Output:

Once this process is complete, open another terminal and issue the command:

npm run start

Sample Output:

You will have the Hyperswitch Control Centre running on port 9000. Access it using the provided URL and you will see this page.

Please create an account by clicking on sign up then use it to log in. Once logged in, you will see this dashboard.

Add a payment processor

The first thing here is to add a payment processor. To achieve that, go to the processors tab. Here, we will set up the Stripe Test.

Provide the name of the API key and the required details.

Select the payment details

Finish the creation.

The payment processor will be created as shown.

Create an API key

An API key is also required. For this, you need to navigate to Developers –> Keys.

Provide the key name and description. You can also set the expiration date for the key of need to

Once created, you will have the key. Copy and download the key as it will be required later.

The created key will be available as shown.

Create Routing

With the Hyperswitch control centre, you have total control over how and where you route your payments. To configure the routes, navigate to workflow –> routing and access the smart routing module.

Here, there are 2 routing ways:

• Volume based routing: This routes payments based on the volume provided.
• Rule based routing: This gives you finer control over payment routing. It allows you to configure the payment parameters like amount, payment_method, card_type etc. with which you can configure multiple rules.

In this guide, we will configure the Volume based routing

Set the name of the route, a description and the profile to be used. You also need to select the processor. For this case, we will use the Stripe processor we created earlier.

Once the changes have been made, save the changes and the route will be available

c. Test Payment with Hyperswitch

Now we can test if our Hyperswitch can process payments. To achieve that, go to the Home page and make a test payment by clicking on Try It Out

You will be granted this page. Here you don’t need to provide your API key as Hyperswitch will take care of that. We will enter the desired amount.

Now in the preview page, you will see the card loading, providing the dummy details provided. For the expiry date put any future dates and any 3-digit figure as the CSV.

Now make the payment and you will see this.

That shows that Hyperswitch is working as desired.

You can see the payments as shown.

Voila!

Verdict

That marks the end of this guide on how to run hyperswitch in Docker Container with Docker Compose. There are many other configs you can make. Feel free to explore them from the official hyperswitch documentation.

Related content:

• Payment solutions for hotels – everything you need to know
• Making It Easier for Payments to Happen
• Install Crater Invoicing Solution on Debian
• How To Install Invoice Ninja on Ubuntu