docs: changes for api ref (#7324)

Co-authored-by: Sanchith Hegde <[email protected]>
juspay · Feb 25, 2025 · d86bb94 · d86bb94
1 parent 120122f
commit d86bb94
Show file tree

Hide file tree

Showing 4 changed files with 169 additions and 65 deletions.
diff --git a/api-reference/api-reference/payments/Introduction--to--payments.mdx b/api-reference/api-reference/payments/Introduction--to--payments.mdx
@@ -0,0 +1,60 @@
+---
+tags: [Payments]
+sidebarTitle: "Getting Started with Payments"
+icon: "circle-play"
+iconType: "solid"
+color: "Green"
+---
+
+The **Hyperswitch Payments API** enables businesses to **accept, process, and manage payments seamlessly**. It supports the entire **payment lifecycle**—from creation to capture, refunds, and disputes—allowing smooth integration of **various payment methods** into any application with minimal complexity.
+
+### How to try your first payment through hyperswitch?
+You have two options to use the Payments API:
+
+1. **Sandbox API Key (Dashboard)** – Quick testing without setup.  
+2. **Self-Deploy** – Create merchants and API keys through Rest API.  
+
+Each option has specific nuances, we have mentioned the differences in the below step by step guide
+<Tip>We recommend using our [Dashboard](https://app.hyperswitch.io/dashboard/login) to generate API Key and setting up Connectors (Step 4)</Tip> for faster trial and simple setup
+<Steps>
+  <Step title="Create a Merchant Account">
+    This account is representative of you or your organization that would like to accept payments from different <Tooltip tip="Can be a payment method or payment service provider">payment connectors</Tooltip>
+    <Steps>
+  <Step title="Hyperswitch Dashboard flow" icon= "box-open">
+    Access the <Tooltip tip="Control Center is a frontend interface for the API to track and test payments">[Dashboard](https://app.hyperswitch.io/dashboard/login)</Tooltip> and sign up -> **Sign up here is equivalent to creating a Merchant Account**
+  </Step>
+  <Step title="Self-Deploy flow" icon="map-pin">
+   Use the admin api key and the [Merchant Account - Create](api-reference/merchant-account/merchant-account--create) endpoint to create your Merchant Account
+  </Step>  
+</Steps>
+  </Step>
+  <Step title="Create API Key">
+   You can now generate an API key that will be the secret key used to authenticate your payment request
+ <Steps>
+  <Step title="Hyperswitch Dashboard flow" icon= "box-open">
+    In Dashboard go to Developer-> API Keys -> +Create New Api Key. This key can be used in your API requests for authentication.
+  </Step>
+  <Step title="Self-Deploy flow" icon="map-pin">
+   Use the admin api key and the [Merchant Account - Create](api-reference/merchant-account/merchant-account--create) endpoint to create your Merchant Account
+  </Step>  
+</Steps>
+  </Step>
+  <Step title="Set up Connectors">
+    Connect the payment [connectors](api-reference/merchant-connector-account/merchant-connector--create) and payment methods that your organization will accept. Connectors could be a payment processor/facilitator/acquirer or a provider of specialized services like Fraud/Accounting
+  <Steps>
+  <Step title="Hyperswitch Dashboard flow" icon= "box-open">
+    In Dashboard go to Connectors -> <Tooltip tip="Adding other connectors (eg. Adyen) will require you to go through their respective documentation">+Connect a Dummy Processor</Tooltip>. Choose the payments methods to enable and complete setup.
+  </Step>
+  <Step title="Self-Deploy flow" icon="map-pin">
+   Use the admin api key and the [Connector Account](api-reference/merchant-connector-account/merchant-connector--create) endpoints to set up a connector
+  </Step>  
+</Steps>
+  </Step>
+  <Step title="Try your first payment">
+    You are all set! Go ahead and try the [Payments API](api-reference/payments/payments--create), be sure to try the different use cases provided
+  </Step>
+  <Step title="We are here to help" icon="circle-info">
+   Test the use cases you are interested in and in case of difficulty, feel free to contact us on our [slack channel](https://join.slack.com/t/hyperswitch-io/shared_invite/zt-2jqxmpsbm-WXUENx022HjNEy~Ark7Orw)
+  </Step>
+</Steps>
+---
diff --git a/api-reference/api-reference/payments/payments--create.mdx b/api-reference/api-reference/payments/payments--create.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: openapi_spec post /payments
----
+---
+<Tip> Use the dropdown on the top right corner of the code snippet to try out different payment scenarios. </Tip>
diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx
@@ -1,15 +1,32 @@
 ---
 tags: [Getting Started]
+title: "👋 Welcome to Hyperswitch API Reference"
+sidebarTitle: "Introduction"
 stoplight-id: 3lmsk7ocvq21v
+icon: "rectangle-code"
+iconType: "solid"
 ---
 
-# 👋 Welcome to Hyperswitch API Reference
-
 Hyperswitch provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library.
 
+<CardGroup horizontal cols={2} row={3}> 
+  <Card horizontal title="Try a Payment" href="api-reference/payments/Introduction--to--payments" icon="money-bill">
+    Explore the versatile payments endpoint, through multiple test scenarios
+  </Card>
+  <Card horizontal title="Refund" href="api-reference/refunds/refunds--create" icon="receipt">
+    Process refunds for completed payments using our API
+  </Card>
+  <Card horizontal title="Save a payment method" href="api-reference/payment-methods/paymentmethods--create" icon="vault">
+    Save customer payment methods securely for future transactions
+  </Card>
+  <Card horizontal title="Self Hosted?" href="api-reference/organization/organization--create" icon="circle-down">
+    Host Hyperswitch on-premise? Utilize our full API suite.
+  </Card>
+</CardGroup>
+
 ## Environment
 
-We have a testing environment referred to "sandbox," which you can set up to test API calls without affecting production data. You can sign up on our Dashboard to get API keys to access Hyperswitch API.
+We have a testing environment referred to <Tooltip tip="Testing environment!">"sandbox</Tooltip>," which you can set up to test API calls without affecting production data. You can sign up on our Dashboard to get API keys to access Hyperswitch API.
 
 Use the following base URLs when making requests to the APIs:
 

diff --git a/api-reference/mint.json b/api-reference/mint.json
@@ -5,6 +5,17 @@
     "dark": "/logo/dark.svg",
     "light": "/logo/light.svg"
   },
+  "topbarLinks": [
+    {
+      "name": "Contact Us",
+      "url": "https://join.slack.com/t/hyperswitch-io/shared_invite/zt-2jqxmpsbm-WXUENx022HjNEy~Ark7Orw"
+    }
+  ], 
+  "topbarCtaButton": {
+    "type": "link",
+    "url": "https://docs.hyperswitch.io/hyperswitch-open-source/overview",
+    "name": "Self-Deploy"
+  },
   "favicon": "/favicon.png",
   "colors": {
     "primary": "#006DF9",
@@ -14,6 +25,9 @@
       "dark": "#242F48"
     }
   },
+  "sidebar": {
+    "items": "card"
+  },
   "tabs": [
     {
       "name": "Locker API Reference",
@@ -39,6 +53,7 @@
         {
           "group": "Payments",
           "pages": [
+            "api-reference/payments/Introduction--to--payments",
             "api-reference/payments/payments--create",
             "api-reference/payments/payments--update",
             "api-reference/payments/payments--confirm",
@@ -101,54 +116,6 @@
             "api-reference/disputes/disputes--list"
           ]
         },
-        {
-          "group": "Organization",
-          "pages": [
-            "api-reference/organization/organization--create",
-            "api-reference/organization/organization--retrieve",
-            "api-reference/organization/organization--update"
-          ]
-        },
-        {
-          "group": "Merchant Account",
-          "pages": [
-            "api-reference/merchant-account/merchant-account--create",
-            "api-reference/merchant-account/merchant-account--retrieve",
-            "api-reference/merchant-account/merchant-account--update",
-            "api-reference/merchant-account/merchant-account--delete",
-            "api-reference/merchant-account/merchant-account--kv-status"
-          ]
-        },
-        {
-          "group": "Business Profile",
-          "pages": [
-            "api-reference/business-profile/business-profile--create",
-            "api-reference/business-profile/business-profile--update",
-            "api-reference/business-profile/business-profile--retrieve",
-            "api-reference/business-profile/business-profile--delete",
-            "api-reference/business-profile/business-profile--list"
-          ]
-        },
-        {
-          "group": "API Key",
-          "pages": [
-            "api-reference/api-key/api-key--create",
-            "api-reference/api-key/api-key--retrieve",
-            "api-reference/api-key/api-key--update",
-            "api-reference/api-key/api-key--revoke",
-            "api-reference/api-key/api-key--list"
-          ]
-        },
-        {
-          "group": "Merchant Connector Account",
-          "pages": [
-            "api-reference/merchant-connector-account/merchant-connector--create",
-            "api-reference/merchant-connector-account/merchant-connector--retrieve",
-            "api-reference/merchant-connector-account/merchant-connector--update",
-            "api-reference/merchant-connector-account/merchant-connector--delete",
-            "api-reference/merchant-connector-account/merchant-connector--list"
-          ]
-        },
         {
           "group": "Payouts",
           "pages": [
@@ -171,15 +138,6 @@
             "api-reference/event/events--manual-retry"
           ]
         },
-        {
-          "group": "GSM (Global Status Mapping)",
-          "pages": [
-            "api-reference/gsm/gsm--create",
-            "api-reference/gsm/gsm--get",
-            "api-reference/gsm/gsm--update",
-            "api-reference/gsm/gsm--delete"
-          ]
-        },
         {
           "group": "Poll",
           "pages": ["api-reference/poll/poll--retrieve-poll-status"]
@@ -221,6 +179,76 @@
         }
       ]
     },
+    {
+      "group": "Admin API based",
+      "pages": [
+        {
+          "group": "Organization",
+          "pages": [
+            "api-reference/organization/organization--create",
+            "api-reference/organization/organization--retrieve",
+            "api-reference/organization/organization--update"
+          ]
+        },
+        {
+          "group": "Merchant Account",
+          "pages": [
+            "api-reference/merchant-account/merchant-account--create",
+            "api-reference/merchant-account/merchant-account--retrieve",
+            "api-reference/merchant-account/merchant-account--update",
+            "api-reference/merchant-account/merchant-account--delete",
+            "api-reference/merchant-account/merchant-account--kv-status"
+          ]
+        },
+        {
+          "group": "Business Profile",
+          "pages": [
+            "api-reference/business-profile/business-profile--create",
+            "api-reference/business-profile/business-profile--update",
+            "api-reference/business-profile/business-profile--retrieve",
+            "api-reference/business-profile/business-profile--delete",
+            "api-reference/business-profile/business-profile--list"
+          ]
+        },
+        {
+          "group": "API Key",
+          "pages": [
+            "api-reference/api-key/api-key--create",
+            "api-reference/api-key/api-key--retrieve",
+            "api-reference/api-key/api-key--update",
+            "api-reference/api-key/api-key--revoke",
+            "api-reference/api-key/api-key--list"
+          ]
+        },
+        {
+          "group": "Merchant Connector Account",
+          "pages": [
+            "api-reference/merchant-connector-account/merchant-connector--create",
+            "api-reference/merchant-connector-account/merchant-connector--retrieve",
+            "api-reference/merchant-connector-account/merchant-connector--update",
+            "api-reference/merchant-connector-account/merchant-connector--delete",
+            "api-reference/merchant-connector-account/merchant-connector--list"
+          ]
+        },
+        {
+          "group": "GSM (Global Status Mapping)",
+          "pages": [
+            "api-reference/gsm/gsm--create",
+            "api-reference/gsm/gsm--get",
+            "api-reference/gsm/gsm--update",
+            "api-reference/gsm/gsm--delete"
+          ]
+        },
+        {
+          "group": "Event",
+          "pages": [
+            "api-reference/event/events--list",
+            "api-reference/event/events--delivery-attempt-list",
+            "api-reference/event/events--manual-retry"
+          ]
+        }
+      ]
+    },
     {
       "group": "Hyperswitch Card Vault",
       "pages": ["locker-api-reference/overview"]
@@ -263,11 +291,9 @@
   "analytics": {
     "gtm": {
       "tagId": "GTM-PLBNKQFQ"
-    }
-  },
-  "analytics": {
+    },
     "mixpanel": {
       "projectToken": "b00355f29d9548d1333608df71d5d53d"
     }
   }
-}
+}