rust/hyperswitch
1
0
Fork 0
mirror of https://github.com/juspay/hyperswitch.git synced 2025-10-28 20:23:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor(openapi_v2): add merchant account v2 openapi (#5588)

Browse Source 
Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
This commit is contained in:
Narayan Bhat
2024-08-12 18:19:08 +05:30
committed by GitHub
parent 116f31cf9b
commit c8943eb289
32 changed files with 1085 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/pr-convention-checks.yml vendored
View File

@ -157,7 +157,7 @@ jobs:
migration_and_schema_changes='true'
fi
if echo "${files_changed}" | grep --quiet --extended-regexp '^api-reference/(openapi_spec.json|openapi_spec_v2.json)$'; then
if echo "${files_changed}" | grep --quiet --extended-regexp '^(api-reference|api-reference-v2)/openapi_spec.json$'; then
openapi_changes='true'
fi

14
.github/workflows/validate-openapi-spec.yml vendored
View File

@ -50,13 +50,13 @@ jobs:
with:
toolchain: stable 2 weeks ago
- name: Generate the OpenAPI spec file
- name: Generate the OpenAPI spec file for V1
shell: bash
run: cargo run -p openapi
run: cargo run -p openapi --features v1
- name: Generate the OpenAPI spec file for V2
shell: bash
run: cargo r -p openapi --no-default-features --features v2
run: cargo run -p openapi --features v2
- name: Install `swagger-cli`
shell: bash
@ -68,17 +68,17 @@ jobs:
- name: Validate the JSON file for V2
shell: bash
run: swagger-cli validate ./api-reference/openapi_spec_v2.json
run: swagger-cli validate ./api-reference-v2/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 -- api-reference/openapi_spec.json api-reference/openapi_spec_v2.json ; then
if ! git diff --quiet --exit-code -- api-reference/openapi_spec.json api-reference-v2/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 api-reference/openapi_spec.json api-reference/openapi_spec_v2.json
git add api-reference/openapi_spec.json api-reference-v2/openapi_spec.json
git commit --message 'docs(openapi): re-generate OpenAPI specification'
git push
fi
@ -88,6 +88,6 @@ jobs:
shell: bash
run: |
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.'
echo '::error::The OpenAPI spec file is not up-to-date. Please re-generate the OpenAPI spec file using `cargo run -p openapi --features v1 && cargo run -p openapi --features v2` and commit it.'
exit 1
fi

3
api-reference-v2/api-reference/merchant-account/merchant-account--create.mdx Normal file
View File

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

3
api-reference-v2/api-reference/merchant-account/merchant-account--retrieve.mdx Normal file
View File

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

3
api-reference-v2/api-reference/merchant-account/merchant-account--update.mdx Normal file
View File

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

0
api-reference/api-reference-v2/merchant-connector-account/merchant-connector--delete.mdx → api-reference-v2/api-reference/merchant-connector-account/delete-connector_accounts.mdx
View File

0
api-reference/api-reference-v2/merchant-connector-account/merchant-connector--retrieve.mdx → api-reference-v2/api-reference/merchant-connector-account/get-connector_accounts.mdx
View File

0
api-reference/api-reference-v2/merchant-connector-account/merchant-connector--create.mdx → api-reference-v2/api-reference/merchant-connector-account/merchant-connector--create.mdx
View File

3
api-reference-v2/api-reference/merchant-connector-account/merchant-connector--delete.mdx Normal file
View File

@ -0,0 +1,3 @@
---
openapi: delete /connector_accounts/{id}
---

3
api-reference-v2/api-reference/merchant-connector-account/merchant-connector--retrieve.mdx Normal file
View File

@ -0,0 +1,3 @@
---
openapi: get /connector_accounts/{id}
---

0
api-reference/api-reference-v2/merchant-connector-account/merchant-connector--update.mdx → api-reference-v2/api-reference/merchant-connector-account/merchant-connector--update.mdx
View File

3
api-reference-v2/api-reference/merchant-connector-account/post-connector_accounts-1.mdx Normal file
View File

@ -0,0 +1,3 @@
---
openapi: post /connector_accounts/{id}
---

3
api-reference-v2/api-reference/merchant-connector-account/post-connector_accounts.mdx Normal file
View File

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

BIN
api-reference-v2/assets/images/image.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 202 KiB

77
api-reference-v2/essentials/error_codes.mdx Normal file
View File

@ -0,0 +1,77 @@
---
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 |
| WE | Webhook Error | Errors related to Webhooks |
| 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 | Provide a valid JWT token to access the APIs |
| IR_18 | 401 | invalid_request_error | "message" | The user is not authorised to update the customer, Contact Org. Admin for the appropriate access. |
| IR_19 | 400 | invalid_request_error | "message" | Please check and retry with correct details. Refer to our API documentation |
| IR_20 | 400 | invalid_request_error | "flow" not supported by the "connector" | Requested flow is not supported for this Connector. |
| IR_21 | 400 | invalid_request_error | Missing required params | Please add the required params in the request. Refer to our API documentation |
| IR_22 | 403 | invalid_request_error | Access forbidden. Not authorized to access this "resource" | Contact Org. Admin for the appropriate access. |
| IR_23 | 400 | invalid_request_error | "message" | Use a supported file provider. Refer to our API documentation |
| IR_24 | 422 | processing_error | Invalid "wallet_name" wallet token | Share the correct wallet token. |
| IR_25 | 400 | invalid_request_error | Cannot delete the default payment method | Check if the Payment method is activated. Refer to Control centre to check this. |
| IR_26 | 400 | invalid_request_error | Invalid Cookie | Recheck the site setting for the cookies. |
| IR_27 | 404 | invalid_request_error | Extended card info does not exist | Recheck the card info shared in the request. |
| IR_28 | 400 | invalid_request_error | "message" | Use a valid currency. Refer to our API documentation |
| IR_29 | 422 | invalid_request_error | "message" | The data format is invalid for this request. Refer to our API documentation |
| IR_30 | 400 | invalid_request_error | Merchant connector account is configured with invalid config | Correct the config for merchant connector account |
| IR_31 | 400 | invalid_request_error | Card with the provided iin does not exist | Check the IIN (Issuer Identification Number) and ensure it is correct. |
| IR_32 | 400 | invalid_request_error | The provided card IIN length is invalid, please provide an iin with 6 or 8 digits | Provide a valid IIN with either 6 or 8 digits. |
| IR_33 | 400 | invalid_request_error | File not found / valid in the request | Ensure the required file is included in the request and is valid. Refer to our API documentation |
| IR_34 | 400 | invalid_request_error | Dispute id not found in the request | Ensure that a valid dispute ID is included in the request. |
| IR_35 | 400 | invalid_request_error | File purpose not found in the request or is invalid | Specify a valid file purpose in the request. |
| IR_36 | 400 | invalid_request_error | File content type not found / valid | Ensure the file content type is specified and is valid. |
| IR_37 | 404 | invalid_request_error | "message" | Check the request for the resource being accessed and ensure it exists. |
| IR_38 | 400 | invalid_request_error | "message" | Check for any duplicate entries in the request and correct them. |
| IR_39 | 400 | invalid_request_error | required payment method is not configured or configured incorrectly for all configured connectors | Verify that the required payment method is correctly configured for all connectors in use. |
| 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 |
| CE_08 | 400 | processing_error | Dispute operation failed while processing with connector. Retry operation | Retry the operation again as dispute failed at the connector |
| CE_09 | 400 | invalid_request_error | Payout validation failed | Retry the operation again with correct Payout details. |
| HE_00 | 422,500 | server_not_available | Resource not available right now, Please try again later. | Please Wait for a few moments and try again. If the error still persists, please reach out to Hyperswitch support |
| HE_01 | 400,422 | duplicate_request | Requested operation(Customer, Payments, Merchants, Refunds etc.) for these identifier already exists. | Please verify the Details(Customer, Payments, Merchants, Refunds, as applicable on the basis of request) and enter valid details. |
| HE_02 | 404 | object_not_found | Requested object(Customer, Payments, Merchants, Refunds etc.) does not exist in our records | Please verify the Details(Customer, Payments, Merchants, Refunds, as applicable on the basis of request) and enter valid details. |
| HE_03 | 500 | validation_error | Validation Failed for the requested operation with the given details. | Please verify the details again and enter valid details |
| HE_04 | 404 | object_not_found | Requested object(Customer, Payments, Merchants, Refunds etc.) does not exist in our records | Please verify the Details(Customer, Payments, Merchants, Refunds, as applicable on the basis of request) and enter valid details. |
| HE_05 | 500 | processing_error | Missing or invalid tenant details. | Please verify the tenant Details and try again. |
| WE_01 | 400 | invalid_request_error | Failed to authenticate the webhook | Please verify the authentication credentials and try again. |
| WE_02 | 400 | invalid_request_error | Bad request received in webhook | Check the request parameters and format, then try again. |
| WE_03 | 500 | router_error | There was some issue processing the webhook | Please try again later. If the issue persists, contact Hyperswitch support. |
| WE_04 | 404 | object_not_found | Webhook resource not found | Ensure the webhook URL is correct and the resource exists. |
| WE_05 | 400 | invalid_request_error | Unable to process the webhook body | Ensure the webhook body is correctly formatted and try again. |
| WE_06 | 400 | invalid_request_error | Merchant Secret set by merchant for webhook source verification is invalid | Verify the Merchant Secret, then try again. |

50
api-reference-v2/essentials/go-live.mdx Normal file
View File

@ -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.

30
api-reference-v2/essentials/rate_limit.mdx Normal file
View File

@ -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.

45
api-reference-v2/essentials/webhooks.mdx Normal file
View File

@ -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.

BIN
api-reference-v2/favicon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.8 KiB

51
api-reference-v2/introduction.mdx Normal file
View File

@ -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" />

29
api-reference-v2/logo/dark.svg Normal file
View File

@ -0,0 +1,29 @@
<svg width="766" height="100" viewBox="0 0 766 100" fill="none" xmlns="http://www.w3.org/2000/svg">
<g clip-path="url(#clip0_1969_1952)">
<path d="M370.801 53.4399C370.801 70.0799 360.581 79.9999 346.441 79.9999C338.621 79.9999 331.811 76.7899 328.701 71.4799V99.0399H317.771V27.6899H327.791L328.691 35.5099C331.801 30.1999 338.411 26.6899 346.431 26.6899C360.061 26.6899 370.791 36.2099 370.791 53.4499L370.801 53.4399ZM359.471 53.4399C359.471 42.9199 353.261 36.3999 344.231 36.3999C335.611 36.2999 329.001 42.9099 329.001 53.5399C329.001 64.1699 335.621 70.2799 344.231 70.2799C352.841 70.2799 359.471 63.9699 359.471 53.4399Z" fill="white"/>
<path d="M428.931 56.3498H389.641C389.841 65.9698 396.151 70.9798 404.171 70.9798C410.181 70.9798 415.201 68.1698 417.301 62.5598H428.431C425.721 72.9798 416.501 79.9998 403.971 79.9998C388.631 79.9998 378.511 69.3798 378.511 53.2398C378.511 37.0998 388.631 26.5798 403.871 26.5798C419.111 26.5798 428.931 36.7998 428.931 52.2398V56.3498ZM389.741 48.7298H417.801C417.201 39.8098 411.291 35.2998 403.871 35.2998C396.451 35.2998 390.541 39.8098 389.741 48.7298Z" fill="white"/>
<path d="M448.281 27.6899C443.181 27.6899 439.051 31.8199 439.051 36.9199V79.0099H450.081V51.6499V39.8199C450.081 38.5499 451.111 37.5099 452.391 37.5099H469.231V27.6899H448.291H448.281Z" fill="white"/>
<path d="M300.14 27.5898L286.01 70.1898L270.77 27.6898H258.94L278.48 78.3098C279.08 79.9098 279.38 81.2198 279.38 82.5198C279.38 83.2298 279.31 83.8798 279.19 84.4798L279.16 84.5898C279.09 84.9098 279.01 85.2098 278.91 85.4998L278.17 88.2098C277.99 88.8798 277.38 89.3398 276.69 89.3398H261.14V99.0598H272.47C280.09 99.0598 286.4 97.2598 290.01 87.2298L311.56 27.6898L300.13 27.5898H300.14Z" fill="white"/>
<path d="M206.82 78.9999H217.74V51.3399C217.74 42.7199 222.45 36.7099 231.17 36.7099C238.79 36.6099 243.5 41.1199 243.5 51.0399V78.9999H254.43V49.3299C254.43 31.7899 243.71 26.5799 233.98 26.5799C226.56 26.5799 220.75 29.4899 217.74 34.2999V6.63989H206.82V78.9999Z" fill="white"/>
<path d="M483.66 63.4699C483.76 68.7799 488.67 71.8899 495.39 71.8899C502.11 71.8899 506.11 69.3799 506.11 64.8699C506.11 60.9599 504.11 58.8599 498.29 57.9499L487.97 56.1499C477.95 54.4499 474.04 49.2299 474.04 41.9199C474.04 32.6999 483.16 26.6899 494.79 26.6899C507.32 26.6899 516.44 32.6999 516.54 42.9299H505.72C505.62 37.7199 501.11 34.8099 494.8 34.8099C488.49 34.8099 484.98 37.3199 484.98 41.5299C484.98 45.2399 487.59 46.9399 493.3 47.9399L503.42 49.7399C512.94 51.4399 517.35 56.1499 517.35 63.8699C517.35 74.4899 507.53 80.0099 495.6 80.0099C482.07 80.0099 472.95 73.4999 472.75 63.4699H483.68H483.66Z" fill="white"/>
<path d="M542.19 66.9799L553.82 27.6899H565.25L576.68 66.9799L586.4 27.6899H597.93L583.4 79.0099H571.07L559.44 39.9199L547.71 79.0099H535.28L520.65 27.6899H532.18L542.2 66.9799H542.19Z" fill="white"/>
<path d="M604.34 6.63989H616.47V18.0699H604.34V6.63989ZM604.94 27.6899H615.86V79.0099H604.94V27.6899Z" fill="white"/>
<path d="M685.32 36.1099C676.8 36.1099 670.99 42.3199 670.99 53.2499C670.99 64.7799 677 70.3899 685.02 70.3899C691.43 70.3899 696.15 66.7799 698.25 59.9699H709.88C707.27 72.3999 697.85 80.0199 685.22 80.0199C669.99 80.0199 659.76 69.3998 659.76 53.2599C659.76 37.1199 669.98 26.5999 685.32 26.5999C697.85 26.5999 707.17 33.7199 709.88 46.1399H698.05C696.25 39.7299 691.33 36.1199 685.32 36.1199V36.1099Z" fill="white"/>
<path d="M642.87 69.2799C642.23 69.2799 641.72 68.7599 641.72 68.1299V37.41H653.65V27.69H641.72V13.95H630.8V22.87C630.8 26.08 629.8 27.68 626.59 27.68H622.18V37.4H630.8V65.0599C630.8 73.9799 635.71 78.99 644.63 78.99H653.55V69.2699H642.88L642.87 69.2799Z" fill="white"/>
<path d="M745.22 26.5799C737.8 26.5799 731.99 29.4899 728.98 34.2999V6.63989H718.06V78.9999H728.98V51.3399C728.98 42.7199 733.69 36.7099 742.41 36.7099C750.03 36.6099 754.74 41.1199 754.74 51.0399V78.9999H765.67V49.3299C765.67 31.7899 754.95 26.5799 745.22 26.5799Z" fill="white"/>
<g clip-path="url(#clip1_1969_1952)">
<path d="M135.792 0H42.875C19.1958 0 0 19.1958 0 42.875C0 66.5542 19.1958 85.75 42.875 85.75H135.792C159.471 85.75 178.667 66.5542 178.667 42.875C178.667 19.1958 159.471 0 135.792 0Z" fill="#006DF9"/>
<path d="M140.261 56.4367C147.751 56.4367 153.822 50.3649 153.822 42.8751C153.822 35.3852 147.751 29.3135 140.261 29.3135C132.771 29.3135 126.699 35.3852 126.699 42.8751C126.699 50.3649 132.771 56.4367 140.261 56.4367Z" fill="white"/>
<path d="M53.2718 53.4511L39.0877 31.4253C38.7683 30.9299 38.0448 30.9299 37.7254 31.4253L23.5413 53.4511C23.1925 53.9888 23.5804 54.6993 24.2224 54.6993H52.5907C53.2327 54.6993 53.6206 53.9888 53.2718 53.4511Z" fill="white"/>
<path d="M100.55 30.353H78.1172C77.3972 30.353 76.8135 30.9367 76.8135 31.6567V54.0899C76.8135 54.8099 77.3972 55.3936 78.1172 55.3936H100.55C101.27 55.3936 101.854 54.8099 101.854 54.0899V31.6567C101.854 30.9367 101.27 30.353 100.55 30.353Z" fill="white"/>
</g>
</g>
<defs>
<clipPath id="clip0_1969_1952">
<rect width="765.66" height="99.05" fill="white"/>
</clipPath>
<clipPath id="clip1_1969_1952">
<rect width="178.667" height="85.75" fill="white"/>
</clipPath>
</defs>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 5.0 KiB

29
api-reference-v2/logo/light.svg Normal file
View File

@ -0,0 +1,29 @@
<svg width="766" height="100" viewBox="0 0 766 100" fill="none" xmlns="http://www.w3.org/2000/svg">
<g clip-path="url(#clip0_1969_1952)">
<path d="M370.801 53.4399C370.801 70.0799 360.581 79.9999 346.441 79.9999C338.621 79.9999 331.811 76.7899 328.701 71.4799V99.0399H317.771V27.6899H327.791L328.691 35.5099C331.801 30.1999 338.411 26.6899 346.431 26.6899C360.061 26.6899 370.791 36.2099 370.791 53.4499L370.801 53.4399ZM359.471 53.4399C359.471 42.9199 353.261 36.3999 344.231 36.3999C335.611 36.2999 329.001 42.9099 329.001 53.5399C329.001 64.1699 335.621 70.2799 344.231 70.2799C352.841 70.2799 359.471 63.9699 359.471 53.4399Z" fill="#242628"/>
<path d="M428.931 56.3498H389.641C389.841 65.9698 396.151 70.9798 404.171 70.9798C410.181 70.9798 415.201 68.1698 417.301 62.5598H428.431C425.721 72.9798 416.501 79.9998 403.971 79.9998C388.631 79.9998 378.511 69.3798 378.511 53.2398C378.511 37.0998 388.631 26.5798 403.871 26.5798C419.111 26.5798 428.931 36.7998 428.931 52.2398V56.3498ZM389.741 48.7298H417.801C417.201 39.8098 411.291 35.2998 403.871 35.2998C396.451 35.2998 390.541 39.8098 389.741 48.7298Z" fill="#242628"/>
<path d="M448.281 27.6899C443.181 27.6899 439.051 31.8199 439.051 36.9199V79.0099H450.081V51.6499V39.8199C450.081 38.5499 451.111 37.5099 452.391 37.5099H469.231V27.6899H448.291H448.281Z" fill="#242628"/>
<path d="M300.14 27.5898L286.01 70.1898L270.77 27.6898H258.94L278.48 78.3098C279.08 79.9098 279.38 81.2198 279.38 82.5198C279.38 83.2298 279.31 83.8798 279.19 84.4798L279.16 84.5898C279.09 84.9098 279.01 85.2098 278.91 85.4998L278.17 88.2098C277.99 88.8798 277.38 89.3398 276.69 89.3398H261.14V99.0598H272.47C280.09 99.0598 286.4 97.2598 290.01 87.2298L311.56 27.6898L300.13 27.5898H300.14Z" fill="#242628"/>
<path d="M206.82 78.9999H217.74V51.3399C217.74 42.7199 222.45 36.7099 231.17 36.7099C238.79 36.6099 243.5 41.1199 243.5 51.0399V78.9999H254.43V49.3299C254.43 31.7899 243.71 26.5799 233.98 26.5799C226.56 26.5799 220.75 29.4899 217.74 34.2999V6.63989H206.82V78.9999Z" fill="#242628"/>
<path d="M483.66 63.4699C483.76 68.7799 488.67 71.8899 495.39 71.8899C502.11 71.8899 506.11 69.3799 506.11 64.8699C506.11 60.9599 504.11 58.8599 498.29 57.9499L487.97 56.1499C477.95 54.4499 474.04 49.2299 474.04 41.9199C474.04 32.6999 483.16 26.6899 494.79 26.6899C507.32 26.6899 516.44 32.6999 516.54 42.9299H505.72C505.62 37.7199 501.11 34.8099 494.8 34.8099C488.49 34.8099 484.98 37.3199 484.98 41.5299C484.98 45.2399 487.59 46.9399 493.3 47.9399L503.42 49.7399C512.94 51.4399 517.35 56.1499 517.35 63.8699C517.35 74.4899 507.53 80.0099 495.6 80.0099C482.07 80.0099 472.95 73.4999 472.75 63.4699H483.68H483.66Z" fill="#242628"/>
<path d="M542.19 66.9799L553.82 27.6899H565.25L576.68 66.9799L586.4 27.6899H597.93L583.4 79.0099H571.07L559.44 39.9199L547.71 79.0099H535.28L520.65 27.6899H532.18L542.2 66.9799H542.19Z" fill="#242628"/>
<path d="M604.34 6.63989H616.47V18.0699H604.34V6.63989ZM604.94 27.6899H615.86V79.0099H604.94V27.6899Z" fill="#242628"/>
<path d="M685.32 36.1099C676.8 36.1099 670.99 42.3199 670.99 53.2499C670.99 64.7799 677 70.3899 685.02 70.3899C691.43 70.3899 696.15 66.7799 698.25 59.9699H709.88C707.27 72.3999 697.85 80.0199 685.22 80.0199C669.99 80.0199 659.76 69.3998 659.76 53.2599C659.76 37.1199 669.98 26.5999 685.32 26.5999C697.85 26.5999 707.17 33.7199 709.88 46.1399H698.05C696.25 39.7299 691.33 36.1199 685.32 36.1199V36.1099Z" fill="#242628"/>
<path d="M642.87 69.2799C642.23 69.2799 641.72 68.7599 641.72 68.1299V37.41H653.65V27.69H641.72V13.95H630.8V22.87C630.8 26.08 629.8 27.68 626.59 27.68H622.18V37.4H630.8V65.0599C630.8 73.9799 635.71 78.99 644.63 78.99H653.55V69.2699H642.88L642.87 69.2799Z" fill="#242628"/>
<path d="M745.22 26.5799C737.8 26.5799 731.99 29.4899 728.98 34.2999V6.63989H718.06V78.9999H728.98V51.3399C728.98 42.7199 733.69 36.7099 742.41 36.7099C750.03 36.6099 754.74 41.1199 754.74 51.0399V78.9999H765.67V49.3299C765.67 31.7899 754.95 26.5799 745.22 26.5799Z" fill="#242628"/>
<g clip-path="url(#clip1_1969_1952)">
<path d="M135.792 0H42.875C19.1958 0 0 19.1958 0 42.875C0 66.5542 19.1958 85.75 42.875 85.75H135.792C159.471 85.75 178.667 66.5542 178.667 42.875C178.667 19.1958 159.471 0 135.792 0Z" fill="#006DF9"/>
<path d="M140.261 56.4367C147.751 56.4367 153.822 50.3649 153.822 42.8751C153.822 35.3852 147.751 29.3135 140.261 29.3135C132.771 29.3135 126.699 35.3852 126.699 42.8751C126.699 50.3649 132.771 56.4367 140.261 56.4367Z" fill="white"/>
<path d="M53.2718 53.4511L39.0877 31.4253C38.7683 30.9299 38.0448 30.9299 37.7254 31.4253L23.5413 53.4511C23.1925 53.9888 23.5804 54.6993 24.2224 54.6993H52.5907C53.2327 54.6993 53.6206 53.9888 53.2718 53.4511Z" fill="white"/>
<path d="M100.55 30.353H78.1172C77.3972 30.353 76.8135 30.9367 76.8135 31.6567V54.0899C76.8135 54.8099 77.3972 55.3936 78.1172 55.3936H100.55C101.27 55.3936 101.854 54.8099 101.854 54.0899V31.6567C101.854 30.9367 101.27 30.353 100.55 30.353Z" fill="white"/>
</g>
</g>
<defs>
<clipPath id="clip0_1969_1952">
<rect width="765.66" height="99.05" fill="white"/>
</clipPath>
<clipPath id="clip1_1969_1952">
<rect width="178.667" height="85.75" fill="white"/>
</clipPath>
</defs>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 5.0 KiB

62
api-reference-v2/mint.json Normal file
View File

@ -0,0 +1,62 @@
{
"$schema": "https://mintlify.com/schema.json",
"name": "Hyperswitch",
"logo": {
"dark": "/logo/dark.svg",
"light": "/logo/light.svg"
},
"favicon": "/favicon.png",
"colors": {
"primary": "#006DF9",
"light": "#006DF9",
"dark": "#006DF9",
"background": {
"dark": "#242F48"
}
},
"tabs": [
{
"name": "API Reference",
"url": "api-reference"
}
],
"navigation": [
{
"group": "Get Started",
"pages": ["introduction"]
},
{
"group": "Essentials",
"pages": [
"essentials/webhooks",
"essentials/error_codes",
"essentials/rate_limit",
"essentials/go-live"
]
},
{
"group": "Merchant Connector Account",
"pages": [
"api-reference/merchant-account/merchant-account--create",
"api-reference/merchant-account/merchant-account--retrieve",
"api-reference/merchant-account/merchant-account--update"
]
},
{
"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"
]
}
],
"footerSocials": {
"github": "https://github.com/juspay/hyperswitch",
"linkedin": "https://www.linkedin.com/company/hyperswitch"
},
"openapi": ["openapi_spec.json"],
"api": {
"maintainOrder": true
}
}

174
api-reference/openapi_spec_v2.json → api-reference-v2/openapi_spec.json
View File

@ -248,6 +248,180 @@
}
]
}
},
"/v2/accounts": {
"post": {
"tags": [
"Merchant Account"
],
"summary": "Merchant Account - Create",
"description": "Merchant Account - Create\n\nCreate a new account for a *merchant* and the *merchant* could be a seller or retailer or client who likes to receive and send payments.\n\nBefore creating the merchant account, it is mandatory to create an organization.",
"operationId": "Create a Merchant Account",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantAccountCreate"
},
"examples": {
"Create a merchant account with merchant details": {
"value": {
"merchant_details": {
"primary_contact_person": "John Doe",
"primary_email": "example@company.com"
},
"merchant_name": "Cloth Store",
"organization_id": "org_abcdefghijklmnop"
}
},
"Create a merchant account with metadata": {
"value": {
"merchant_name": "Cloth Store",
"metadata": {
"key_1": "John Doe",
"key_2": "Trends"
},
"organization_id": "org_abcdefghijklmnop"
}
},
"Create a merchant account with minimal fields": {
"value": {
"merchant_name": "Cloth Store",
"organization_id": "org_abcdefghijklmnop"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Merchant Account Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantAccountResponse"
}
}
}
},
"400": {
"description": "Invalid data"
}
},
"security": [
{
"admin_api_key": []
}
]
}
},
"/v2/accounts/{id}": {
"get": {
"tags": [
"Merchant Account"
],
"summary": "Merchant Account - Retrieve",
"description": "Merchant Account - Retrieve\n\nRetrieve a *merchant* account details.",
"operationId": "Retrieve a Merchant Account",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The unique identifier for the merchant account",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Merchant Account Retrieved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantAccountResponse"
}
}
}
},
"404": {
"description": "Merchant account not found"
}
},
"security": [
{
"admin_api_key": []
}
]
},
"post": {
"tags": [
"Merchant Account"
],
"summary": "Merchant Account - Update",
"description": "Merchant Account - Update\n\nUpdates details of an existing merchant account. Helpful in updating merchant details such as email, contact details, or other configuration details like webhook, routing algorithm etc",
"operationId": "Update a Merchant Account",
"parameters": [
{
"name": "account_id",
"in": "path",
"description": "The unique identifier for the merchant account",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantAccountUpdate"
},
"examples": {
"Update Merchant Details": {
"value": {
"merchant_details": {
"primary_contact_person": "John Doe",
"primary_email": "example@company.com"
}
}
},
"Update merchant name": {
"value": {
"merchant_id": "merchant_abc",
"merchant_name": "merchant_name"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Merchant Account Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantAccountResponse"
}
}
}
},
"404": {
"description": "Merchant account not found"
}
},
"security": [
{
"admin_api_key": []
}
]
}
}
},
"components": {

372
api-reference-v2/rust_locker_open_api_spec.yml Normal file
View File

@ -0,0 +1,372 @@
openapi: "3.0.2"
info:
title: Tartarus - OpenAPI 3.0
description: |-
This the the open API 3.0 specification for the card locker.
This is used by the [hyperswitch](https://github.com/juspay/hyperswitch) for storing card information securely.
version: "1.0"
tags:
- name: Key Custodian
description: API used to initialize the locker after deployment.
- name: Data
description: CRUD APIs to for working with data to be stored in the locker
- name: Cards
description: CRUD APIs to for working with cards data to be stored in the locker (deprecated)
paths:
/custodian/key1:
post:
tags:
- Key Custodian
summary: Provide Key 1
description: Provide the first key to unlock the locker
operationId: setKey1
requestBody:
description: Provide key 1 to unlock the locker
content:
application/json:
schema:
$ref: "#/components/schemas/Key"
required: true
responses:
"200":
description: Key 1 provided
content:
text/plain:
schema:
$ref: "#/components/schemas/Key1Set"
/custodian/key2:
post:
tags:
- Key Custodian
summary: Provide Key 2
description: Provide the first key to unlock the locker
operationId: setKey2
requestBody:
description: Provide key 2 to unlock the locker
content:
application/json:
schema:
$ref: "#/components/schemas/Key"
required: true
responses:
"200":
description: Key 2 provided
content:
text/plain:
schema:
$ref: "#/components/schemas/Key2Set"
/custodian/decrypt:
post:
tags:
- Key Custodian
summary: Unlock the locker
description: Unlock the locker with the key1 and key2 provided
responses:
"200":
description: Successfully Unlocked
content:
text/plain:
schema:
$ref: "#/components/schemas/Decrypt200"
/health:
get:
summary: Get Health
description: To check whether the application is up
responses:
"200":
description: Health is good
content:
text/plain:
schema:
$ref: "#/components/schemas/Health"
/data/add:
post:
tags:
- Cards
- Data
summary: Add Data in Locker
description: Add sensitive data in the locker
requestBody:
description: The request body might be JWE + JWS encrypted when using middleware
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/StoreDataReq"
- $ref: "#/components/schemas/JWEReq"
required: true
responses:
"200":
description: Store Data Response
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/StoreDataRes"
- $ref: "#/components/schemas/JWERes"
/data/delete:
post:
tags:
- Cards
- Data
summary: Delete Data from Locker
description: Delete sensitive data from the locker
requestBody:
description: The request body might be JWE + JWS encrypted when using middleware
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/DeleteDataReq"
- $ref: "#/components/schemas/JWEReq"
required: true
responses:
"200":
description: Delete Data Response
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/DeleteDataRes"
- $ref: "#/components/schemas/JWERes"
/data/retrieve:
post:
tags:
- Cards
- Data
summary: Retrieve Data from Locker
description: Retrieve sensitive data from the locker
requestBody:
description: The request body might be JWE + JWS encrypted when using middleware
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/RetrieveDataReq"
- $ref: "#/components/schemas/JWEReq"
required: true
responses:
"200":
description: Retrieve Data Response
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/RetrieveDataRes"
- $ref: "#/components/schemas/JWERes"
/data/fingerprint:
post:
tags:
- Cards
- Data
summary: Get or insert the card fingerprint
description: Get or insert the card fingerprint
requestBody:
description: Provide card number and hash key
content:
application/json:
schema:
$ref: "#/components/schemas/FingerprintReq"
required: true
responses:
"200":
description: Fingerprint Response
content:
application/json:
schema:
$ref: "#/components/schemas/FingerprintRes"
components:
schemas:
Key:
type: object
properties:
key:
type: string
example: 801bb63c1bd51820acbc8ac20c674675
required:
- key
StoreDataReq:
title: StoreDataReq
type: object
properties:
merchant_id:
type: string
example: m0100
merchant_customer_id:
type: string
example: HsCustomer1
requester_card_reference:
type: string
example: 3ffdf1e5-7f38-4f26-936f-c66a6f4296fa
card:
$ref: "#/components/schemas/Card"
enc_card_data:
type: string
example: "qwe4tyusdfg"
RetrieveDataReq:
title: RetrieveDataReq
type: object
properties:
merchant_id:
type: string
example: m0100
merchant_customer_id:
type: string
example: HsCustomer1
card_reference:
type: string
example: 3ffdf1e5-7f38-4f26-936f-c66a6f4296fa
DeleteDataReq:
title: DeleteDataReq
type: object
properties:
merchant_id:
type: string
example: m0100
merchant_customer_id:
type: string
example: HsCustomer1
card_reference:
type: string
example: 3ffdf1e5-7f38-4f26-936f-c66a6f4296fa
FingerprintReq:
type: object
properties:
card:
$ref: "#/components/schemas/FingerprintCardData"
hash_key:
type: string
example: Hash1
JWEReq:
title: JWEReq
type: object
properties:
header:
type: string
iv:
type: string
encrypted_payload:
type: string
tag:
type: string
encrypted_key:
type: string
RetrieveRes:
title: RetrieveRes
oneOf:
- type: object
properties:
card:
$ref: "#/components/schemas/Card"
- type: object
properties:
enc_card_data:
type: string
Card:
title: Card
type: object
required:
- card_number
properties:
card_number:
type: string
name_on_card:
type: string
card_exp_month:
type: string
card_exp_year:
type: string
card_brand:
type: string
card_isin:
type: string
nick_name:
type: string
FingerprintCardData:
type: object
properties:
card_number:
type: string
example: 4242424242424242
Key1Set:
title: Key1Set
type: string
# summary: Response after setting key1
description: Received Key1
example: Received Key1
Key2Set:
title: Key2Set
type: string
# description: Response after setting key2
description: Received Key2
example: Received Key2
Decrypt200:
title: Decrypt200
type: string
# description: Response if the locker key custodian decryption was successful
description: Decryption successful
example: Decryption successful
Health:
title: Health
type: string
# description: Response when the health is good
description: health is good
example: health is good
StoreDataRes:
title: StoreDataRes
type: object
description: Response received if the data was stored successfully
properties:
status:
type: string
enum: [Ok]
payload:
type: object
properties:
card_reference:
type: string
RetrieveDataRes:
title: RetrieveDataRes
type: object
description: Response received with the sensitive data, associated to the card reference
properties:
status:
type: string
enum: [Ok]
payload:
$ref: "#/components/schemas/RetrieveRes"
DeleteDataRes:
title: DeleteDataRes
type: object
description: Response received if the data deletion was successful
properties:
status:
type: string
enum: [Ok]
FingerprintRes:
type: object
description: Response received if the fingerprint insertion or retrieval was successful
properties:
status:
type: string
enum: [Ok]
payload:
type: object
properties:
fingerprint:
type: string
JWERes:
title: JWERes
type: object
description: JWE encrypted response equivalent
properties:
header:
type: string
iv:
type: string
encrypted_payload:
type: string
tag:
type: string
encrypted_key:
type: string

59
api-reference/mint_v2.json
View File

@ -1,59 +0,0 @@
{
"$schema": "https://mintlify.com/schema.json",
"name": "Hyperswitch",
"logo": {
"dark": "/logo/dark.svg",
"light": "/logo/light.svg"
},
"favicon": "/favicon.png",
"colors": {
"primary": "#006DF9",
"light": "#006DF9",
"dark": "#006DF9",
"background": {
"dark": "#242F48"
}
},
"tabs": [
{
"name": "API Reference",
"url": "api-reference"
},
{
"name": "Locker API Reference",
"url": "locker-api-reference"
}
],
"navigation": [
{
"group": "Get Started",
"pages": ["introduction"]
},
{
"group": "Essentials",
"pages": [
"essentials/webhooks",
"essentials/error_codes",
"essentials/rate_limit",
"essentials/go-live"
]
},
{
"group": "Merchant Connector Account",
"pages": [
"api-reference-v2/merchant-connector-account/merchant-connector--create",
"api-reference-v2/merchant-connector-account/merchant-connector--retrieve",
"api-reference-v2/merchant-connector-account/merchant-connector--update",
"api-reference-v2/merchant-connector-account/merchant-connector--delete"
]
}
],
"footerSocials": {
"github": "https://github.com/juspay/hyperswitch",
"linkedin": "https://www.linkedin.com/company/hyperswitch"
},
"openapi": ["openapi_spec_v2.json", "rust_locker_open_api_spec.yml"],
"api": {
"maintainOrder": true
}
}

1
crates/openapi/Cargo.toml
View File

@ -16,7 +16,6 @@ common_utils = { version = "0.1.0", path = "../common_utils" }
router_env = { version = "0.1.0", path = "../router_env" }
[features]
default = ["v1"]
v2 = ["api_models/v2", "api_models/customer_v2", "api_models/merchant_account_v2", "api_models/routing_v2", "api_models/merchant_connector_account_v2"]
v1 = ["api_models/v1"]

1
crates/openapi/src/lib.rs
View File

@ -1,2 +1 @@
mod openapi;
pub mod routes;

11
crates/openapi/src/main.rs
View File

@ -10,9 +10,12 @@ fn main() {
let relative_file_path = "api-reference/openapi_spec.json";
#[cfg(feature = "v2")]
let relative_file_path = "api-reference/openapi_spec_v2.json";
let relative_file_path = "api-reference-v2/openapi_spec.json";
#[cfg(any(feature = "v1", feature = "v2"))]
let mut file_path = router_env::workspace_path();
#[cfg(any(feature = "v1", feature = "v2"))]
file_path.push(relative_file_path);
#[cfg(feature = "v1")]
@ -21,6 +24,7 @@ fn main() {
let openapi = <openapi_v2::ApiDoc as utoipa::OpenApi>::openapi();
#[allow(clippy::expect_used)]
#[cfg(any(feature = "v1", feature = "v2"))]
std::fs::write(
file_path,
openapi
@ -28,5 +32,10 @@ fn main() {
.expect("Failed to serialize OpenAPI specification as JSON"),
)
.expect("Failed to write OpenAPI specification to file");
#[cfg(any(feature = "v1", feature = "v2"))]
println!("Successfully saved OpenAPI specification file at '{relative_file_path}'");
#[cfg(not(any(feature = "v1", feature = "v2")))]
println!("No feature enabled to generate OpenAPI specification, please enable either 'v1' or 'v2' feature");
}

5
crates/openapi/src/openapi_v2.rs
View File

@ -74,6 +74,11 @@ Never share your secret api keys. Keep them guarded and secure.
routes::merchant_connector_account::connector_retrieve,
routes::merchant_connector_account::connector_update,
routes::merchant_connector_account::connector_delete,
// Routes for merchant account
routes::merchant_account::merchant_account_create,
routes::merchant_account::merchant_account_retrieve,
routes::merchant_account::merchant_account_update,
),
components(schemas(
common_utils::types::MinorUnit,

126
crates/openapi/src/routes/merchant_account.rs
View File

@ -1,3 +1,4 @@
#[cfg(feature = "v1")]
/// Merchant Account - Create
///
/// Create a new account for a *merchant* and the *merchant* could be a seller or retailer or client who likes to receive and send payments.
@ -41,6 +42,65 @@
)]
pub async fn merchant_account_create() {}
#[cfg(feature = "v2")]
/// Merchant Account - Create
///
/// Create a new account for a *merchant* and the *merchant* could be a seller or retailer or client who likes to receive and send payments.
///
/// Before creating the merchant account, it is mandatory to create an organization.
#[utoipa::path(
post,
path = "/v2/accounts",
request_body(
content = MerchantAccountCreate,
examples(
(
"Create a merchant account with minimal fields" = (
value = json!({
"merchant_name": "Cloth Store",
"organization_id": "org_abcdefghijklmnop"
})
)
),
(
"Create a merchant account with merchant details" = (
value = json!({
"merchant_name": "Cloth Store",
"organization_id": "org_abcdefghijklmnop",
"merchant_details": {
"primary_contact_person": "John Doe",
"primary_email": "example@company.com"
}
})
)
),
(
"Create a merchant account with metadata" = (
value = json!({
"merchant_name": "Cloth Store",
"organization_id": "org_abcdefghijklmnop",
"metadata": {
"key_1": "John Doe",
"key_2": "Trends"
}
})
)
),
)
),
responses(
(status = 200, description = "Merchant Account Created", body = MerchantAccountResponse),
(status = 400, description = "Invalid data")
),
tag = "Merchant Account",
operation_id = "Create a Merchant Account",
security(("admin_api_key" = []))
)]
pub async fn merchant_account_create() {}
#[cfg(feature = "v1")]
/// Merchant Account - Retrieve
///
/// Retrieve a *merchant* account details.
@ -58,6 +118,25 @@ pub async fn merchant_account_create() {}
)]
pub async fn retrieve_merchant_account() {}
#[cfg(feature = "v2")]
/// Merchant Account - Retrieve
///
/// Retrieve a *merchant* account details.
#[utoipa::path(
get,
path = "/v2/accounts/{id}",
params (("id" = String, Path, description = "The unique identifier for the merchant account")),
responses(
(status = 200, description = "Merchant Account Retrieved", body = MerchantAccountResponse),
(status = 404, description = "Merchant account not found")
),
tag = "Merchant Account",
operation_id = "Retrieve a Merchant Account",
security(("admin_api_key" = []))
)]
pub async fn merchant_account_retrieve() {}
#[cfg(feature = "v1")]
/// Merchant Account - Update
///
/// Updates details of an existing merchant account. Helpful in updating merchant details such as email, contact details, or other configuration details like webhook, routing algorithm etc
@ -75,12 +154,6 @@ pub async fn retrieve_merchant_account() {}
})
)
),
("Update merchant name" = (
value = json!({
"merchant_id": "merchant_abc",
"merchant_name": "merchant_name"
})
)),
("Update webhook url" = (
value = json!({
"merchant_id": "merchant_abc",
@ -107,6 +180,46 @@ pub async fn retrieve_merchant_account() {}
)]
pub async fn update_merchant_account() {}
#[cfg(feature = "v2")]
/// Merchant Account - Update
///
/// Updates details of an existing merchant account. Helpful in updating merchant details such as email, contact details, or other configuration details like webhook, routing algorithm etc
#[utoipa::path(
post,
path = "/v2/accounts/{id}",
request_body (
content = MerchantAccountUpdate,
examples(
(
"Update merchant name" = (
value = json!({
"merchant_id": "merchant_abc",
"merchant_name": "merchant_name"
})
)
),
("Update Merchant Details" = (
value = json!({
"merchant_details": {
"primary_contact_person": "John Doe",
"primary_email": "example@company.com"
}
})
)
),
)),
params (("account_id" = String, Path, description = "The unique identifier for the merchant account")),
responses(
(status = 200, description = "Merchant Account Updated", body = MerchantAccountResponse),
(status = 404, description = "Merchant account not found")
),
tag = "Merchant Account",
operation_id = "Update a Merchant Account",
security(("admin_api_key" = []))
)]
pub async fn merchant_account_update() {}
#[cfg(feature = "v1")]
/// Merchant Account - Delete
///
/// Delete a *merchant* account
@ -124,6 +237,7 @@ pub async fn update_merchant_account() {}
)]
pub async fn delete_merchant_account() {}
#[cfg(feature = "v1")]
/// Merchant Account - KV Status
///
/// Toggle KV mode for the Merchant Account

3
crates/storage_impl/src/payouts/payouts.rs
View File

@ -684,7 +684,8 @@ impl<T: DatabaseStore> PayoutsInterface for crate::RouterStore<T> {
_merchant_id: &common_utils::id_type::MerchantId,
_filters: &PayoutFetchConstraints,
_storage_scheme: MerchantStorageScheme,
) -> error_stack::Result<Vec<(Payouts, PayoutAttempt, DieselCustomer)>, StorageError> {
) -> error_stack::Result<Vec<(Payouts, PayoutAttempt, Option<DieselCustomer>)>, StorageError>
{
todo!()
}