refactor(openapi): move openapi to a separate folder (#4859)

.github/workflows/validate-openapi-spec.yml

@@ -60,17 +60,17 @@ jobs:
 
       - name: Validate the JSON file
         shell: bash
-        run: swagger-cli validate ./openapi/openapi_spec.json
+        run: swagger-cli validate ./api-reference/openapi_spec.json
 
       - name: Commit the JSON file if it is not up-to-date
         # PR originated from same repository
         if: ${{ (github.event_name == 'pull_request') && (github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name) }}
         shell: bash
         run: |
-          if ! git diff --quiet --exit-code -- openapi/openapi_spec.json ; then
+          if ! git diff --quiet --exit-code -- api-reference/openapi_spec.json ; then
             git config --local user.name 'hyperswitch-bot[bot]'
             git config --local user.email '148525504+hyperswitch-bot[bot]@users.noreply.github.com'
-            git add openapi/openapi_spec.json
+            git add api-reference/openapi_spec.json
             git commit --message 'docs(openapi): re-generate OpenAPI specification'
             git push
           fi
@@ -79,7 +79,7 @@ jobs:
         if: ${{ (github.event_name == 'merge_group') || ((github.event_name == 'pull_request') && (github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name)) }}
         shell: bash
         run: |
-          if ! git diff --quiet --exit-code -- openapi/openapi_spec.json ; then
+          if ! git diff --quiet --exit-code -- api-reference/openapi_spec.json ; then
             echo '::error::The OpenAPI spec file is not up-to-date. Please re-generate the OpenAPI spec file using `cargo run -p openapi` and commit it.'
             exit 1
           fi

api-reference/_snippets/snippet-example.mdx

@@ -0,0 +1,3 @@
+## My Snippet
+
+<Info>This is an example of a reusable snippet</Info>

api-reference/api-reference/api-key/api-key--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /api_keys/{merchant_id)
+---

api-reference/api-reference/api-key/api-key--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /api_keys/{merchant_id}/{key_id}
+---

api-reference/api-reference/api-key/api-key--revoke.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /api_keys/{merchant_id)/{key_id}
+---

api-reference/api-reference/api-key/api-key--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /api_keys/{merchant_id}/{key_id}
+---

api-reference/api-reference/blocklist/delete-blocklist.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /blocklist
+---

api-reference/api-reference/blocklist/get-blocklist.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /blocklist
+---

api-reference/api-reference/blocklist/post-blocklist.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /blocklist
+---

api-reference/api-reference/blocklist/post-blocklisttoggle.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /blocklist/toggle
+---

api-reference/api-reference/business-profile/business-profile--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /account/{account_id}/business_profile
+---

api-reference/api-reference/business-profile/business-profile--delete.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /account/{account_id}/business_profile/{profile_id}
+---

api-reference/api-reference/business-profile/business-profile--list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /account/{account_id}/business_profile
+---

api-reference/api-reference/business-profile/business-profile--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /account/{account_id}/business_profile/{profile_id}
+---

api-reference/api-reference/business-profile/business-profile--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /account/{account_id}/business_profile/{profile_id}
+---

api-reference/api-reference/customer-set-default-payment-method/customers--set-default-payment-method.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /{customer_id}/payment_methods/{payment_method_id}/default
+---

api-reference/api-reference/customers/customers--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /customers
+---

api-reference/api-reference/customers/customers--delete.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec delete /customers/{customer_id}
+---

api-reference/api-reference/customers/customers--list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /customers/list
+---

api-reference/api-reference/customers/customers--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /customers/{customer_id}
+---

api-reference/api-reference/customers/customers--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /customers/{customer_id}
+---

api-reference/api-reference/disputes/disputes--list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /disputes/list
+---

api-reference/api-reference/disputes/disputes--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /disputes/{dispute_id}
+---

api-reference/api-reference/event/events--delivery-attempt-list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /events/{merchant_id_or_profile_id}/{event_id}/attempts
+---

api-reference/api-reference/event/events--list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /events/{merchant_id_or_profile_id}
+---

api-reference/api-reference/event/events--manual-retry.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /events/{merchant_id_or_profile_id}/{event_id}/retry
+---

api-reference/api-reference/gsm/gsm--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /gsm
+---

api-reference/api-reference/gsm/gsm--delete.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /gsm/delete
+---

api-reference/api-reference/gsm/gsm--get.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /gsm/get
+---

api-reference/api-reference/gsm/gsm--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /gsm/update
+---

api-reference/api-reference/mandates/mandates--customer-mandates-list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /customers/{customer_id}/mandates
+---

api-reference/api-reference/mandates/mandates--retrieve-mandate.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /mandates/{mandate_id}
+---

api-reference/api-reference/mandates/mandates--revoke-mandate.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /mandates/revoke/{mandate_id}
+---

api-reference/api-reference/merchant-account/merchant-account--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /accounts
+---

api-reference/api-reference/merchant-account/merchant-account--delete.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /accounts/{account_id}
+---

api-reference/api-reference/merchant-account/merchant-account--kv-status.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /accounts/{account_id}/kv
+---

api-reference/api-reference/merchant-account/merchant-account--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /accounts/{account_id}
+---

api-reference/api-reference/merchant-account/merchant-account--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /accounts/{account_id}
+---

api-reference/api-reference/merchant-connector-account/merchant-connector--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /accounts/{account_id}/connectors
+---

api-reference/api-reference/merchant-connector-account/merchant-connector--delete.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /accounts/{account_id}/connectors/{connector_id}
+---

api-reference/api-reference/merchant-connector-account/merchant-connector--list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /accounts/{account_id}/connectors
+---

api-reference/api-reference/merchant-connector-account/merchant-connector--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /accounts/{account_id}/connectors/{connector_id}
+---

api-reference/api-reference/merchant-connector-account/merchant-connector--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /accounts/{account_id}/connectors/{connector_id}
+---

api-reference/api-reference/payment-methods/list-customer-saved-payment-methods-for-a-payment.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /customers/payment_methods
+---

api-reference/api-reference/payment-methods/list-payment-methods-for-a-customer.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /customers/{customer_id}/payment_methods
+---

api-reference/api-reference/payment-methods/list-payment-methods-for-a-merchant.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /account/payment_methods
+---

api-reference/api-reference/payment-methods/payment-method--delete.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec delete /payment_methods/{method_id}
+---

api-reference/api-reference/payment-methods/payment-method--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /payment_methods/{method_id}
+---

api-reference/api-reference/payment-methods/payment-method--set-default-payment-method-for-customer.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /{customer_id}/payment_methods/{payment_method_id}/default
+---

api-reference/api-reference/payment-methods/payment-method--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payment_methods/{method_id}/update
+---

api-reference/api-reference/payment-methods/paymentmethods--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payment_methods
+---

api-reference/api-reference/payments/payments--cancel.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payments/{payment_id}/cancel
+---

api-reference/api-reference/payments/payments--capture.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payments/{payment_id}/capture
+---

api-reference/api-reference/payments/payments--complete-authorize.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /{payment_id}/complete_authorize
+---

api-reference/api-reference/payments/payments--confirm.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payments/{payment_id}/confirm
+---

api-reference/api-reference/payments/payments--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payments
+---

api-reference/api-reference/payments/payments--external-3ds-authentication.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /payments/{payment_id}/3ds/authentication
+---

api-reference/api-reference/payments/payments--incremental-authorization.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /payments/{payment_id}/incremental_authorization
+---

api-reference/api-reference/payments/payments--list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /payments/list
+---

api-reference/api-reference/payments/payments--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /payments/{payment_id}
+---

api-reference/api-reference/payments/payments--session-token.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payments/session_tokens
+---

api-reference/api-reference/payments/payments--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payments/{payment_id}
+---

api-reference/api-reference/payments/payments-link--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /payment_link/{payment_link_id}
+---

api-reference/api-reference/payouts/payouts--cancel.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payouts/{payout_id}/cancel
+---

api-reference/api-reference/payouts/payouts--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payouts/create
+---

api-reference/api-reference/payouts/payouts--filter.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /payouts/list
+---

api-reference/api-reference/payouts/payouts--fulfill.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payouts/{payout_id}/fulfill
+---

api-reference/api-reference/payouts/payouts--list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /payouts/list
+---

api-reference/api-reference/payouts/payouts--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /payouts/{payout_id}
+---

api-reference/api-reference/payouts/payouts--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /payouts/{payout_id}
+---

api-reference/api-reference/poll/poll--retrieve-poll-status.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /poll/status/{poll_id}
+---

api-reference/api-reference/refunds/refunds--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /refunds
+---

api-reference/api-reference/refunds/refunds--list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /refunds/list
+---

api-reference/api-reference/refunds/refunds--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /refunds/{refund_id}
+---

api-reference/api-reference/refunds/refunds--update.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /refunds/{refund_id}
+---

api-reference/api-reference/routing/routing--activate-config.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /routing/{algorithm_id}/activate
+---

api-reference/api-reference/routing/routing--create.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /routing
+---

api-reference/api-reference/routing/routing--deactivate.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /routing/deactivate
+---

api-reference/api-reference/routing/routing--list.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /routing
+---

api-reference/api-reference/routing/routing--retrieve-config.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /routing/active
+---

api-reference/api-reference/routing/routing--retrieve-default-config.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /routing/default
+---

api-reference/api-reference/routing/routing--retrieve-default-for-profile.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /routing/default/profile
+---

api-reference/api-reference/routing/routing--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /routing/{algorithm_id}
+---

api-reference/api-reference/routing/routing--update-default-config.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /routing/default
+---

api-reference/api-reference/routing/routing--update-default-for-profile.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /routing/default/profile/{profile_id}
+---

api-reference/api-reference/schemas/outgoing--webhook.mdx

@@ -0,0 +1,3 @@
+---
+openapi-schema: OutgoingWebhook
+---

api-reference/essentials/error_codes.mdx

@@ -0,0 +1,60 @@
+---
+title: Error Codes
+---
+
+Hyperswitch uses Error codes, types, and messages to communicate errors during API calls. There are three types of error codes:
+
+| Error Code | Type                  | Description                                                  |
+| ---------- | --------------------- | ------------------------------------------------------------ |
+| IR         | Invalid Request Error | Error caused due to invalid fields and values in API request |
+| CE         | Connector Error       | Errors originating from connector’s end                      |
+| HE         | Hyperswitch Error     | Errors originating from Hyperswitch’s end                    |
+
+| Error Codes | HTTP Status codes                     | Error Type            | Error message                                                                                                                                                       | Error Handling                                                                                                                                                                       |
+| ----------- | ------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| IR_00       | 501                                   | server_not_available  | This API is under development and will be made available soon                                                                                                       | No action required. If you require this feature, please reach out to Hyperswitch support                                                                                             |
+| IR_01       | 401                                   | invalid_request_error | API key not provided or invalid API key used. Provide the API key in the Authorization header using api-key (e.g api-key: API_KEY) or create a new API key from the dashboard | Provide the API key in the Authorization header using api-key (e.g api-key: API_KEY) or create a new API key from the dashboard                                                                |
+| IR_02       | 404                                   | invalid_request_error | Unrecognized request URL                                                                                                                                            | Please recheck and enter the correct request URL. Refer to our API documentation                                                                                                        |
+| IR_03       | 405                                   | invalid_request_error | The HTTP method is not applicable for this API                                                                                                                      | Please recheck the HTTP method used in the request. Refer to our API documentation                                                                                                      |
+| IR_04       | 400                                   | invalid_request_error | Missing required param: “field_name”                                                                                                                                | Please pass the missing required parameter. Refer to our API documentation                                                                                                              |
+| IR_05       | 422                                   | invalid_request_error | “field_name” contains invalid data. Expected format is “expected_format”                                                                                            | Please pass the data in the expected format. Refer to our API documentation                                                                                                                 |
+| IR_06       | 400                                   | invalid_request_error | “message”                                                                                                                                                           | Refer to our API documentation for required fields and format                                                                                                                           |
+| IR_07       | 400                                   | invalid_request_error | Invalid value provided: “field_name”                                                                                                                                | Provide a valid value for the required fields in the expected format. Refer to our API documentation                                                                                          |
+| IR_08       | 400                                   | invalid_request_error | Client secret was not provided                                                                                                                                      | Provide the client secret received in payments/create API response                                                                                                                   |
+| IR_09       | 400                                   | invalid_request_error | The client_secret provided does not match the client_secret associated with the Payment                                                                             | Provide the same client secret received in payments/create API response for the corresponding payment                                                                                |
+| IR_10       | 400                                   | invalid_request_error | Customer has an existing mandate/subscription                                                                                                                           | Cancel the active mandates/subscriptions for the customer before proceeding to delete the customer data                                                                              |
+| IR_11       | 400                                   | invalid_request_error | Customer has already been redacted                                                                                                                                  | Customer has already been redacted. No action required                                                                                                                               |
+| IR_12       | 400                                   | invalid_request_error | Reached the maximum refund attempts                                                                                                                                     | Maximum refund attempts reached for this payment. Please contact Hyperswitch support for attempting more refunds for the same payment                                                |
+| IR_13       | 400                                   | invalid_request_error | Refund amount exceeds the payment amount                                                                                                                            | Please verify and pass a refund amount equal to or less than the payment amount                                                                                                    |
+| IR_14       | 400                                   | invalid_request_error | This Payment could not be “current_flow” because it has a “field_name” of “current_value”. The expected state is “states”                                           | Please verify the status of the payment and make sure that you are performing an action that is allowed for the current status of the payment                                        |
+| IR_15       | 400                                   | invalid_request_error | Invalid Ephemeral Key for the customer                                                                                                                              | Please pass the right Ephemeral key for the customer                                                                                                                                 |
+| IR_16       | 400                                   | invalid_request_error | “message”                                                                                                                                                           | Typically used when information involving multiple fields or previously provided information doesn’t satisfy a condition. Refer to our API documentation for required fields and format |
+| IR_17       | 401                                   | invalid_request_error | Access forbidden, an invalid JWT token was used                                                                                                                        | Please provide a valid JWT token to access the APIs                                                                                                                                  |
+| CE_00       | Status codes shared by the connectors | connector_error       | “message”                                                                                                                                                           | The error code and message passed from the connectors. Refer to the respective connector’s documentation for more information on the error                                           |
+| CE_01       | 400                                   | processing_error      | Payment failed during authorization with the connector. Retry payment                                                                                                   | Retry the payment again as payment failed at the connector during authorization                                                                                                      |
+| CE_02       | 400                                   | processing_error      | Payment failed during authentication with the connector. Retry payment                                                                                                  | Retry the payment again as payment failed at the connector during authentication                                                                                                     |
+| CE_03       | 400                                   | processing_error      | Capture attempt failed while processing with the connector                                                                                                              | Capture failed for the payment at the connector. Please retry the payment                                                                                                            |
+| CE_04       | 400                                   | processing_error      | The card data is invalid                                                                                                                                            | Invalid card data passed. Please pass valid card data                                                                                                                                |
+| CE_05       | 400                                   | processing_error      | The card has expired                                                                                                                                                | Card expired. Please pass valid card data                                                                                                                                            |
+| CE_06       | 400                                   | processing_error      | Refund failed while processing with the connector. Retry refund                                                                                                         | Refund failed to process at the connector. Please retry refund                                                                                                                       |
+| CE_07       | 400                                   | processing_error      | Verification failed while processing with the connector. Retry operation                                                                                                | Retry the operation again as verification failed at the connector                                                                                                                    |
+| HE_00       | 500                                   | server_not_available  | Something went wrong                                                                                                                                                | Please retry the operation. If the error still persists, please reach out to Hyperswitch support                                                                                         |
+| HE_01       | 400                                   | duplicate_request     | Duplicate refund request. Refund already attempted with the refund ID                                                                                               | Please verify the refund id and no action required if the refund is already attempted                                                                                                |
+| HE_01       | 400                                   | duplicate_request     | Duplicate mandate request. Mandate already attempted with the Mandate ID                                                                                            | Please verify the mandate id and no action required if the mandate is already created                                                                                                |
+| HE_01       | 400                                   | duplicate_request     | The merchant account with the specified details already exists in our records                                                                                       | Please verify the merchant account details and no action required if the merchant account is already created                                                                         |
+| HE_01       | 400                                   | duplicate_request     | The merchant connector account with the specified details already exists in our records                                                                             | Please verify the merchant connector account details and no action required if the merchant connector account is already created                                                     |
+| HE_01       | 400                                   | duplicate_request     | The payment method with the specified details already exists in our records                                                                                         | Please verify the mandate id and no action required if the mandate is already created                                                                                                |
+| HE_02       | 400                                   | object_not_found      | Refund does not exist in our records                                                                                                                                | Please verify the refund details and enter valid details                                                                                                                             |
+| HE_02       | 400                                   | object_not_found      | Customer does not exist in our records                                                                                                                              | Please verify the customer details and enter valid details                                                                                                                           |
+| HE_02       | 400                                   | object_not_found      | Payment does not exist in our records                                                                                                                               | Please verify the payment details and enter valid details                                                                                                                            |
+| HE_02       | 400                                   | object_not_found      | Payment method does not exist in our records                                                                                                                        | Please verify the payment method details and enter valid details                                                                                                                     |
+| HE_02       | 400                                   | object_not_found      | Merchant account does not exist in our records                                                                                                                      | Please verify the merchant account details and enter valid details                                                                                                                   |
+| HE_02       | 400                                   | object_not_found      | Merchant connector account does not exist in our records                                                                                                            | Please verify the merchant connector details and enter valid details                                                                                                                 |
+| HE_02       | 400                                   | object_not_found      | Resource ID does not exist in our records                                                                                                                           | Please verify the resource ID and enter valid details                                                                                                                                |
+| HE_02       | 400                                   | object_not_found      | Mandate does not exist in our records                                                                                                                               | Please verify the mandate details and enter valid details                                                                                                                            |
+| HE_03       | 400                                   | validation_error      | Refunds not possible through Hyperswitch. Please raise Refunds through the “connector” dashboard                                                                        | Please raise refunds request from the respective connector’s dashboard as the connectors don’t provide a Refunds API for Hyperswitch to process                                      |
+| HE_03       | 400                                   | validation_error      | Mandate Validation Failed                                                                                                                                           | Please verify the mandate details again and enter valid details                                                                                                                      |
+| HE_04       | 400                                   | validation_error      | The payment has not succeeded yet. Please pass a successful payment to initiate refund                                                                              | Please verify the request parameters and retry the payment. If the error still persists, please reach out to Hyperswitch support                                                     |
+| HE_04       | 400                                   | object_not_found      | Successful payment not found for the given payment id                                                                                                               | Please verify the payment details and status as you can attempt refunds only for payments with success status                                                                        |
+| HE_04       | 400                                   | object_not_found      | The connector provided in the request is incorrect or not available                                                                                                 | Please verify your connector configuration and provide a valid connector that is enabled for your account                                                                            |
+| HE_04       | 400                                   | object_not_found      | Address does not exist in our records                                                                                                                               | Please verify the address details and pass valid address details                                                                                                                     |

api-reference/essentials/go-live.mdx

@@ -0,0 +1,50 @@
+---
+title: Go-live Checklist
+---
+
+Refer to this checklist for a seamless transition as you prepare to go live with your integration.
+
+<Warning>
+The connector configurations set up in the sandbox need to be replicated on the Hyperswitch production account.
+</Warning>
+
+### Signing of Hyperswitch services agreement
+
+- [ ] Ensure that the Hyperswitch services agreement is signed and shared with the Hyperswitch team. In case you need any help, please drop an email to biz@hyperswitch.io.
+
+<Warning>
+The Hyperswitch team will share your production Hyperswitch credentials once the above process is completed.
+</Warning>
+
+### 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. Drop an email to biz@hyperswitch.io if you need any support with PCI AOC.
+
+### 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](https://juspay-78.mintlify.app/essentials/webhooks#configuring-webhooks) on our dashboard to receive notifications for different events.
+- [ ] Update Hyperswitch's webhook endpoints on your connector's Dashboard. [Refer here](https://juspay-78.mintlify.app/essentials/webhooks#configuring-webhooks) 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](https://juspay-78.mintlify.app/essentials/error_codes)).
+- [ ] Ensure your Unified Checkout (SDK) integration is set up to handle all the possible error scenarios (refer this [link](https://hyperswitch.io/docs/sdkIntegrations/unifiedCheckoutWeb/errorCodes)).
+- [ ] Ensure that your integration can handle the entire payments lifecycle and test various scenarios using actual payment details.
+
+### 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](https://hyperswitch.io/docs/sdkIntegrations/unifiedCheckoutWeb/customization) of Unified Checkout.

api-reference/essentials/rate_limit.mdx

@@ -0,0 +1,30 @@
+---
+title: Rate Limits
+---
+
+The Hyperswitch API has multiple checks in place to enhance its stability when faced with sudden surges of incoming traffic. Merchants who send numerous requests in rapid succession could encounter error responses indicated by the status code 429.
+
+<Warning>
+  The default rate limit for all Hyperswitch APIs is **80 requests per second**.
+  Reach out to biz@hyperswitch.io if you have a requirement for higher limits.
+</Warning>
+
+## How to handle rate limits
+
+Effectively handling rate limit 429 errors is crucial for maintaining a seamless user experience.
+
+- Implement retry mechanisms with progressively increasing intervals to avoid overwhelming the system with repeated requests.
+- To proactively manage these errors, monitoring tools can help track usage patterns and provide insights for adjusting rate limits as necessary.
+- Ultimately, a well-orchestrated strategy for managing 429 errors not only prevents disruption but also fosters positive user engagement by transparently addressing limitations and promoting responsible API usage.
+
+## Understanding API locking
+
+If you see a 429 error with the following error message, it is due to API locking and not due to rate limiting:
+
+```text
+At this moment, access to this object is restricted due to ongoing utilization by another API request or an ongoing Hyperswitch process. Retry after some time if this error persists.
+```
+
+API locking is a robust feature that empowers us to proactively secure and optimize access to our APIs. Our API locks objects on some operations to prevent the disruption caused by concurrent workloads that could potentially lead to inconsistent outcomes.
+
+This proactive measure not only ensures the continued integrity and performance of our APIs but also guarantees a high standard of security for our users. Once triggered, the API lock initiates a controlled pause in access, preventing any potential threats from compromising the system.

api-reference/essentials/webhooks.mdx

@@ -0,0 +1,45 @@
+# Webhooks
+
+Webhooks are HTTP-based real-time push notifications that Hyperswitch would use for instant status communication to your server. Webhooks are vital in payments for the following reasons:
+
+- Preventing merchants from losing business due to delayed status communication (say, in case of flight or movie reservations where there is a need for instant payment confirmation).
+- Prevent payment reconciliation issues where payments change from “Failed” to “Succeeded”.
+- Providing the best payment experience for the end-user by instantly communicating payment status and fulfilling the purchase.
+
+## Configuring Webhooks
+<Steps>
+<Step title="Create an endpoint on your server">You would need to set up a dedicated HTTPS or HTTP endpoint on your server with a URL as a webhook listener that will receive push notifications in the form of a POST request with JSON payload from the Hyperswitch server</Step>
+<Step title="Update your webhook endpoint on Hyperswitch Dashboard"> Update the above endpoint on your Hyperswitch dashboard under Settings -> Webhooks</Step>
+<Step title= "Update Hyperswitch’s webhook endpoints on your connector Dashboard">In order for Hyperswitch to receive updates from the connectors you have selected, you would need to update Hyperswitch’s corresponding endpoints on your respective connector dashboard instead of your webhook endpoints</Step>
+</Steps>
+
+Hyperswitch’s webhook endpoint format is as follows:
+
+| Environment | Webhook Endpoint |
+| ----------- | ---------------- |
+| Sandbox     | sandbox.hyperswitch.io/webhooks/`{merchant_id}`/`{connector_name}` |
+| Production  | api.hyperswitch.io/webhooks/`{merchant_id}`/`{connector_name}`|
+
+## Handling Webhooks
+
+- **Select the events for Webhooks:** On the same page on the dashboard, select the events for which you would like to receive notifications. Currently, Webhooks are available on Hyperswitch for the following events:
+
+    1. payment_succeeded
+    2. payment_failed
+    3. payment_processing
+    4. action_required
+    5. refund_succeeded
+    6. refund_failed
+    7. dispute_opened
+    8. dispute_expired
+    9. dispute_accepted
+    10. dispute_cancelled
+    11. dispute_challenged
+    12. dispute_won
+    13. dispute_lost
+
+<Info>Click [**here**](https://juspay-78.mintlify.app/api-reference/schemas/outgoing--webhook) to see the webhook payload your endpoint would need to parse for each of the above events</Info>
+
+- **Return a 2xx response:** Your server must return a successful 2xx response on successful receipt of webhooks.
+
+- **Retries:** In case of 3xx, 4xx, or 5xx response or no response from your endpoint for webhooks, Hyperswitch has a retry mechanism that tries sending the webhooks again up to 3 times before marking the event as failed.

api-reference/introduction.mdx

@@ -0,0 +1,51 @@
+---
+tags: [Getting Started]
+stoplight-id: 3lmsk7ocvq21v
+---
+
+# 👋 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.
+
+## 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.
+
+Use the following base URLs when making requests to the APIs:
+
+| Environment | Base URL                       |
+| ----------- | ------------------------------ |
+| Sandbox     | https://sandbox.hyperswitch.io |
+| Production  | https://api.hyperswitch.io     |
+
+<Note> If you **do not hold a PCI certification** to collect and store card data on your servers, we recommend using [**Unified Checkout**](https://hyperswitch.io/docs/sdkIntegrations/unifiedCheckoutWeb/#unified-checkout) to accept card information from users. </Note>
+
+## Authentication and API keys
+
+Hyperswitch authenticates your API requests using your account’s API keys. Each account has two API keys for authentication:
+
+| Key                  | Example         | When to Use                                                                                                                              |
+| -------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Secret key (API-key) | `snd_c69***`    | Used to authenticate API requests from your merchant server. **Don’t expose this key** on a website or embed it in a mobile application. |
+| Publishable key      | `pk_snd_3b3***` | Used to authenticate API requests from your app’s client. Can be publicly-accessible in your web or mobile app’s client-side code.       |
+
+<Check>
+Get your [API key](https://app.hyperswitch.io/developers?tabIndex=1) and [Publishable Key](https://app.hyperswitch.io/home)
+</Check>
+<Check>
+[Postman Collection](https://www.postman.com/hyperswitch/workspace/hyperswitch-development/collection/25176162-630b5353-7002-44d1-8ba1-ead6c230f2e3)
+</Check>
+
+## Payment Status Lifecycle
+Hyperswitch handles the complex functionality of a comprehensive payments flow through the Payments object that transitions through multiple states during its payments lifecycle. Given below are the various statuses a payment can have:
+| Payment Status           | Description                                                                                                                                                                                                 |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| requires_payment_method  | Once you create a payment through payments/create endpoint with no payment method attached to it, the payments object transitions to ‘requires_payment_method’.                                             |
+| requires_confirmation    | After attaching a payment method through payments/update endpoint, the payments object requires you to confirm the payment.                                                                                 |
+| requires_customer_action | Once the payment is confirmed through payments/confirm endpoint, if additional authentication is required, the payments object transitions to this state.                                                   |
+| requires_capture         | If you want to do separate authorize and capture, setting capture field to ‘manual’ during payments/create or confirm call will transition the payment object to this state after customer action succeeds. |
+| processing               | In case of automatic capture, the payments object transitions to processing state post confirm call and subsequent customer authentication if available.                                                    |
+| succeeded                | The payments object reaches success state post confirmation of successful processing from the payment processor.                                                                                            |
+| failed                   | The payments object transitions to a failed state when the payment processor confirms the processing failure.                                                                                               |
+| expired                  | You can expire the payments object while it is in any state except when it is under ‘processing’ or ‘succeeded’ state.                                                                                      |
+  <img src="assets/images/image.png" />

api-reference/locker-api-reference/cards/add-data-in-locker.mdx

@@ -0,0 +1,3 @@
+---
+openapi: rust_locker_open_api_spec post /data/add
+---

api-reference/locker-api-reference/cards/delete-data-from-locker.mdx

@@ -0,0 +1,3 @@
+---
+openapi: rust_locker_open_api_spec post /data/delete
+---

api-reference/locker-api-reference/cards/get-or-insert-the-card-fingerprint.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /data/fingerprint
+---

api-reference/locker-api-reference/cards/retrieve-data-from-locker.mdx

@@ -0,0 +1,3 @@
+---
+openapi: rust_locker_open_api_spec post /data/retrieve
+---

api-reference/locker-api-reference/key-custodian/provide-key-1.mdx

@@ -0,0 +1,3 @@
+---
+openapi: rust_locker_open_api_spec post /custodian/key1
+---

api-reference/locker-api-reference/key-custodian/provide-key-2.mdx

@@ -0,0 +1,3 @@
+---
+openapi: rust_locker_open_api_spec post /custodian/key2
+---

api-reference/locker-api-reference/key-custodian/unlock-the-locker.mdx

@@ -0,0 +1,3 @@
+---
+openapi: rust_locker_open_api_spec post /custodian/decrypt
+---