README.md

icon
clipboard-question

For On-Prem Setup

Prerequisites

In order to use Hyperswitch for accepting digital payments through a consumer facing website or mobile application there are three main prerequisites

Resources	Account with cloud service provider (AWS/ GCP/Own Cloud) to host Hyperswitch application Contractual relationship and active processing account with payment processor or acquirer (this will be in the form of API keys or merchant identifier)
Technical Know How	For deploying and managing application using Kubernetes Handling a Web application written in Rust using Postgres (primary datastore), Redis (distributed key-value store for cached lookups), Prometheus/Grafana (monitoring), S3/CDN (serving static files)
Ensuring Compliance	Refer here to find out which level of PCI compliance applies to your business. Report on Compliance (ROC): Engage an independent third-party Qualified Security Assessor (QSA) certified by the PCI-SSC to perform the PCI audit and share the findings. The ROC will be prepared by the QSA at the end of the PCI compliance activity. This is required only if your online business processes greater than 1 million card transactions per annum. Quarterly Network scans: Engage an Approved Scanning Vendor for conducting quarterly network scans and submitting the scan reports to the payment processor/ acquirer Self Assessment Questionnaire (SAQ): This is an assessment which can be self-completed by a business without engaging an Independent PCI Auditor, if your business processes less than 1 million card transactions per annum. A person responsible for the payment infrastructure within your organization fills out the SAQ. This could be the stakeholder who is the closest to your payment infrastructure - your Dev Ops Manager, or Information Security Officer, or CTO.

Here's a quick summary of everything you would need for going live with Hyperswitch:

Security

• Keep the system hidden from external access; instead, use a front-end system or a reverse proxy as a protective layer in front of it.
• Make sure to follow our security guidelines for various components in your set up.

API Keys

• Change all the default values for all API key fields in the config file ( Ref). This applies whether you are using Helm charts or not.

Apple Pay Certificate

• To enable Apple Pay payments, request the required certificate: Hyperswitch-app.server.secrets.apple_pay_merchant_cert.
  Follow the official setup guide: Apple Pay Setup.

Deploying the Application

On Kubernetes	deploy-on-kubernetes-using-helm
On AWS	deploy-hyperswitch-on-aws

{% hint style="info" %} The above installation guides include vault as well, but you will need to activate the vault by following the steps mentioned in this guide. {% endhint %}

Outgoing Proxy

• Set up an outgoing proxy outside the Kubernetes cluster for all external communication originating from the Hyperswitch application.
• Direct all outbound traffic through this proxy for monitoring and control purposes.

Incoming Traffic Management

• Route incoming traffic to the Hyperswitch-server through an incoming proxy.
• This proxy should handle traffic filtering(WAF), rate limiting, request validation, and integration with DDoS protection services before traffic reaches the Kubernetes cluster.

{% hint style="warning" %} Hyperswitch does not share card BIN data automatically. BIN (Bank Identification Number) data helps identify the card issuer, card type, and country of issuance. This is available as an add-on service. Reach out to us at [email protected] to access. {% endhint %}

Monitoring

• Make sure logs are being printed for all components in your setup
• Aggregate your logs across instances and setup a logging system (e.g. Grafana Loki) for storing and viewing your logs
• Make sure your metrics pipeline is setup and provides visibility into both application and system performance

PCI Compliance

• Make sure your system is meeting the PCI compliance requirements for your business
• If you are storing card data make sure your card vault is set up as per our instructions.

Connector Configurations

• Configure all the required connectors using production credentials on the Hyperswitch production dashboard and enable the required payment methods.
• Ensure that the payment methods are enabled on the connector (payment processor) dashboard.
• Enable raw card processing for each connector. Some connectors offer this as a dashboard toggle feature. Some processors might need you to share a PCI Attestation of Compliance over email to enable this.

{% hint style="info" %} To access the PCI Attestation of Compliance (AOC) document on Hyperswitch, simply navigate to the Compliance section under settings in the Hyperswitch Dashboard. If you need further assistance, you can also email at [email protected] {% endhint %}

Integrate with your app

• Make sure your API keys are not exposed on the front-end (website/mobile app)
• Avoid duplication or storage of your API keys in multiple locations
• Test your integration and make sure all scenarios in the payments lifecycle is handled
• Make sure your application (Frontend/Backend) is set up to handle all the possible error scenarios
• Keep track of new releases/bug fixes and make sure to keep your system updated

​Secure your api-keys

• Make sure your secret key (api-key) is not exposed on the front-end (website/mobile app).
• Ensure that your workflow avoids the duplication or storage of your API keys in multiple locations.

​Set up Webhooks

• Configure your webhook endpoint on our dashboard to receive notifications for different events.
• Update Hyperswitch’s webhook endpoints on your connector’s Dashboard. Refer here for detailed instructions.
• Update the connector secret key in our dashboard for us to authenticate webhooks sent by your connector.

​Secure your Payments

• Make sure you decrypt and verify the signed payload sent along with the payment status in your return URL.
• Always verify the payment amount and payment status before fulfilling your customer’s shopping cart/service request.

​Error Handling

• Make sure your API integration is set up to handle all the possible error scenarios (refer this link).
• Ensure your Unified Checkout (SDK) integration is set up to handle all the possible error scenarios (refer this link).
• Ensure that your integration can handle the entire payments lifecycle and test various scenarios using actual payment details.

{% hint style="warning" %} For more details, kindly refer to the state machine diagrams. {% endhint %}

​Customize and sanity check the payment experience

• Ensure the pay button is properly highlighted to the customer.
• Ensure a blended look and feel of the payment experience using the styling APIs of Unified Checkout.

{% hint style="success" %} You are good to go to run Hyperswitch in production and provide your customers with a safe, reliable, and smooth payment experience. {% endhint %}