docs: update connector guide #8739

nfarah86 · 2025-07-24T01:48:29Z

Type of Change

Description

Updating the connector documentation

Additional Changes

This PR modifies the API contract
This PR modifies the database schema
This PR modifies application configuration/environment variables

Motivation and Context

Make it easier for developers to contribute

How did you test it?

Checklist

I formatted the code cargo +nightly fmt --all
I addressed lints thrown by cargo clippy
I reviewed the submitted code
I added unit tests for my changes where possible

semanticdiff-com · 2025-07-24T01:48:31Z

Review changes with

nfarah86 · 2025-07-24T01:49:09Z

This is not ready, getting early feedback

nfarah86 · 2025-07-31T17:37:35Z

This is ready for review

add_connector.md

nfarah86 · 2025-08-08T23:47:08Z

@deepanshu-iiitu incorporated your feedback, if you want to take a look

…on Flow

…ms, reworked the tests instructions, added more details for the open api generator

…n utility functions

…rs based on pr feedback

SanchithHegde

Can you do the same for the rest of the source code links, please use permalinks instead of links to code on the main branch.

SanchithHegde · 2025-08-13T15:42:33Z

add_connector.md

+* Familiarity with the Connector API you’re integrating
+* A locally set up and running Router repository
+* API credentials for testing (sign up for sandbox/UAT credentials on the connector’s website).
+* Need help? Join the [Hyperswitch Slack Channel](https://join.slack.com/t/hyperswitch-io/shared_invite/zt-39d4w0043-CgAyb75Kn0YldNyZpd8hWA). We also have weekly office hours every Thursday at 8:00 AM PT (11:00 AM ET, 4:00 PM BST, 5:00 PM CEST, and 8:30 PM IST). Link to office hours are shared in the **#general channel**.


Do we want to include the inviter link here?

SanchithHegde · 2025-08-13T15:44:57Z

add_connector.md

+From the root of the project, generate a new connector by running the following command. Use a single-word name for your `ConnectorName`:
+
+```bash
+sh scripts/add_connector.sh <ConnectorName> <ConnectorBaseUrl>


When we're running this script, we would need cargo-generate tool to be installed. Have we documented anywhere that it must be installed?

SanchithHegde · 2025-08-13T15:47:51Z

add_connector.md

+
+---
+
+### 1. Flow Summary Table


Nit: The source code links in this table may go stale, if new lines are added in the file. We can consider including permalinks to lines in code instead, if that helps.

SanchithHegde · 2025-08-13T15:49:11Z

add_connector.md

+1. **Tokenization** – e.g., Billwerk’s implementation:  
+   - [Tokenization](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_connectors/src/connectors/billwerk.rs#L178-L271)  
+   - [Authorization](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_connectors/src/connectors/billwerk.rs#L273-L366)  


Same here, please use permalinks instead.

SanchithHegde · 2025-08-13T15:49:27Z

add_connector.md

+- **Authorize.net** – [code](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_connectors/src/connectors/authorizedotnet.rs#L401-L497)  
+  Builds `CreateTransactionRequest` directly from payment data in `get_request_body()`.  
+
+- **Helcim** – [code](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_connectors/src/connectors/helcim.rs#L295-L385)  
+  Chooses purchase (auto‑capture) or preauth endpoint in `get_url()` and processes payment data directly.  
+
+- **Deutsche Bank** – [code](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_connectors/src/connectors/deutschebank.rs#L330-L461)  
+  Selects flow based on 3DS and payment type (card or direct debit).  


Here as well, use permalinks instead.

SanchithHegde · 2025-08-13T15:52:46Z

add_connector.md

+- 4xx → [`get_error_response`](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_connectors/src/connectors/billwerk.rs#L256)
+- 5xx → [`get_5xx_error_response`](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_connectors/src/connectors/billwerk.rs#L264)
+- 2xx → [`handle_response`](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_connectors/src/connectors/billwerk.rs#L332)


Same here, use permalinks instead.

SanchithHegde · 2025-08-13T15:53:43Z

add_connector.md

+- `mod.rs` - This file implements the standardized Hyperswitch connector interface using the transformers.
+
+### The `mod.rs` Implementation Pattern
+The file creates the bridge between the data transformation logic (defined in `transformers.rs`) and the connector interface requirements. It serves as the main connector implementation file that brings together all the components defined in the transformers module and implements all the required traits for payment processing. Looking at the connector template structure [`connector-template/mod.rs:54-67`](https://github.com/juspay/hyperswitch/blob/main/connector-template/mod.rs#L54-L67), you can see how it:


Same here, use permalinks.

SanchithHegde · 2025-08-13T15:54:06Z

add_connector.md

 ```

- `get_error_response` method to manage error responses. As the handling of checkout errors remains consistent across various flows, we've incorporated it from the `build_error_response` method within the `ConnectorCommon` trait.
+## ConnectorCommon: The Foundation Trait
+The `ConnectorCommon` trait defines the standardized interface required by Hyperswitch (as outlined in [`crates/hyperswitch_interfaces/src/api.rs`](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_interfaces/src/api.rs#L319-L367) and acts as the bridge to your PSP-specific logic in `transformers.rs`. The `connector-template/mod.rs` file implements this trait using the data types and transformation functions from `transformers.rs`. This allows Hyperswitch to interact with your connector in a consistent, processor-agnostic manner. Every connector must implement the `ConnectorCommon` trait, which provides essential connector properties:


Same here, use permalinks instead.

SanchithHegde · 2025-08-13T15:54:26Z

add_connector.md

+- **Defined in `api.rs`**  
+  [`crates/hyperswitch_interfaces/src/api.rs:150–153`](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_interfaces/src/api.rs#L150)  
+  Provides the standardized interface contracts for connector integration.

-**PaymentCapture :** This trait extends the `api::ConnectorIntegration `trait with specific types related to manual payment capture.
+- **Implemented in `mod.rs`**  
+  Each connector’s main file (`mod.rs`) implements the trait methods for specific payment flows like authorize, capture, refund, etc. You can see how the Tsys connector implements [ConnectorIntegration](https://github.com/juspay/hyperswitch/blob/main/crates/hyperswitch_connectors/src/connectors/tsys.rs#L219)


Same here, use permalinks instead.

SanchithHegde · 2025-08-13T15:56:03Z

add_connector.md


-**RefundSync :** This trait extends the `api::ConnectorIntegration `trait with specific types related to refunds retrieve.
+### Request/Response Flow  


Here as well, we can use permalinks instead wherever source code links are included.

nfarah86 self-assigned this Jul 24, 2025

nfarah86 added the Developer Experience Product enhancements to enhance developer experience label Jul 24, 2025

nfarah86 requested a review from a team as a code owner July 24, 2025 01:48

nfarah86 linked an issue Jul 24, 2025 that may be closed by this pull request

Update add_connector contributing guide #8722

Open

nfarah86 force-pushed the update-connector-guide branch 4 times, most recently from 341aa93 to d2e7796 Compare July 31, 2025 17:31

nfarah86 requested a review from deepanshu-iiitu August 5, 2025 22:35

nfarah86 force-pushed the update-connector-guide branch from 07524e8 to 6af9f32 Compare August 5, 2025 23:24

deepanshu-iiitu reviewed Aug 6, 2025

View reviewed changes

add_connector.md Outdated Show resolved Hide resolved

add_connector.md Show resolved Hide resolved

AkshayaFoiger previously approved these changes Aug 7, 2025

View reviewed changes

nfarah86 dismissed AkshayaFoiger’s stale review via 2b801b7 August 8, 2025 23:46

nfarah86 force-pushed the update-connector-guide branch from 6af9f32 to 2b801b7 Compare August 8, 2025 23:46

deepanshu-iiitu previously approved these changes Aug 11, 2025

View reviewed changes

nfarah86 force-pushed the update-connector-guide branch from 2b801b7 to da92600 Compare August 11, 2025 19:29

nfarah86 dismissed deepanshu-iiitu’s stale review via 0c392fb August 11, 2025 19:36

nfarah86 changed the title ~~Update connector guide~~ DOCS: Update connector guide Aug 11, 2025

deepanshu-iiitu previously approved these changes Aug 12, 2025

View reviewed changes

AkshayaFoiger previously approved these changes Aug 12, 2025

View reviewed changes

nfarah86 dismissed stale reviews from AkshayaFoiger and deepanshu-iiitu via b697b7f August 12, 2025 21:39

nfarah86 added 4 commits August 12, 2025 14:40

added Development Environment Setup & Configuration to be more detailed

db04386

updated syntax

2873e7b

working through the setup

5cc02bd

wip- add a connector

779e361

nfarah86 added 17 commits August 12, 2025 14:40

docs(openapi):update connector guide for Pre-processing + Authorizati…

ef6d3d4

…on Flow

docs(openapi):update connector guide for Authorization Flow

b34c01c

docs(openapi):update connector guide for Authorization Flow- syntax

ecc78f2

docs(openapi):update connector guide for Authorization Flow- syntax

cc6e1a1

docs(openapi): removed the payment flows to gitbook with image diagra…

8595ca2

…ms, reworked the tests instructions, added more details for the open api generator

docs(openapi): started working on the implementation flow

cc10247

docs(openapi): added error reponse and field mappings

df55c1d

docs(openapi): improved the error handling function description

7cabce5

docs(openapi): wrote common connector, connector interface, and commo…

8f0f161

…n utility functions

docs(openapi): added the ui details

3344ea5

docs(openapi): writing and formatting cleanup until code walkthrough

9d6084c

docs(openapi): update toc

447ad15

added URLs and minor cleanup

6ad5005

docs(openapi): updated the flow types with a direct auth example

f1c1603

docs(openapi): updated doc for required fields and disclosure on erro…

dc0b768

…rs based on pr feedback

docs(openapi): updated doc for URL to payment flows

353c7e7

docs(openapi): updated IST typo

371489c

nfarah86 force-pushed the update-connector-guide branch from b697b7f to 371489c Compare August 12, 2025 21:40

AkshayaFoiger approved these changes Aug 13, 2025

View reviewed changes

deepanshu-iiitu approved these changes Aug 13, 2025

View reviewed changes

SanchithHegde changed the title ~~DOCS: Update connector guide~~ docs: Update connector guide Aug 13, 2025

SanchithHegde changed the title ~~docs: Update connector guide~~ docs: update connector guide Aug 13, 2025

SanchithHegde reviewed Aug 13, 2025

View reviewed changes


		RefundSync : This trait extends the `api::ConnectorIntegration `trait with specific types related to refunds retrieve.
		### Request/Response Flow

docs: update connector guide #8739

Are you sure you want to change the base?

docs: update connector guide #8739

Uh oh!

Conversation

nfarah86 commented Jul 24, 2025

Type of Change

Description

Additional Changes

Motivation and Context

How did you test it?

Checklist

Uh oh!

semanticdiff-com bot commented Jul 24, 2025

Uh oh!

nfarah86 commented Jul 24, 2025

Uh oh!

nfarah86 commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nfarah86 commented Aug 8, 2025

Uh oh!

SanchithHegde left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nfarah86 commented Jul 31, 2025 •

edited

Loading