# Add Connector Flow

> Add Connector Flow is an Agent Skill for development published in the juspay/hyperswitch-prism repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Adds one or more payment flows (Authorize, Capture, Refund, Void, PSync, RSync, webhooks, etc.) to an existing connector in the connector-service (UCS) Rust codebase. Use when a connector already exists but is missing specific flow implementations. Handles dependency validation and sequential implementation order.

- Skill name: `add-connector-flow`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/juspay/hyperswitch-prism/blob/HEAD/.skills/add-connector-flow/SKILL.md
- Repository: juspay/hyperswitch-prism (1,405 GitHub stars when collected)

## SKILL.md

# Add Connector Flow

## Overview

Adds specific payment flows to an existing connector.

**MANDATORY SUBAGENT DELEGATION: You are the orchestrator. You MUST delegate every step
to a subagent using the prompts in `references/subagent-prompts.md`. Do NOT implement
code, run tests, or review quality yourself. Spawn subagents and coordinate their outputs.**

**Inputs:** connector name + list of flows to add (e.g., "add Refund and RSync to AcmePay")
**Output:** requested flows implemented, tested, and quality-reviewed

## Flow Dependencies

Flows must be implemented in dependency order. A flow cannot be added unless its
prerequisites already exist or are also being added in the same batch.

| Flow | Prerequisites |
|------|--------------|
| Authorize | None (foundation) |
| PSync | Authorize |
| Capture | Authorize |
| Void | Authorize |
| Refund | Authorize |
| RSync | Refund |
| SetupMandate | Authorize |
| RepeatPayment | SetupMandate |
| IncomingWebhook | PSync |
| CreateAccessToken | None |
| CreateOrder | None |
| CreateConnectorCustomer | None |
| PaymentMethodToken | Authorize |
| AcceptDispute | None |
| SubmitEvidence | None |
| DefendDispute | None |

Full dependency graph and resolution algorithm: `references/flow-dependencies.md`

## Critical Conventions

Include in every subagent prompt:

- Use `RouterDataV2` (NEVER `RouterData`), `ConnectorIntegrationV2` (NEVER `ConnectorIntegration`)
- Import from `domain_types` (NEVER `hyperswitch_domain_models`)
- NEVER hardcode status values -- always map via `From`/`TryFrom`
- Use macros for all flows. Every flow in BOTH `create_all_prerequisites!` and `macro_connector_implementation!`
- `generic_type: T` always present in `macro_connector_implementation!` for ALL flows
- Auth via `req.connector_config` (NOT `connector_auth_type`)
- No `unwrap()`, no None-hardcoded fields

---

## Workflow: Orchestrator Sequence

**Full subagent prompts:** `references/subagent-prompts.md`

### Step 1: State Analysis & Dependency Validation (Subagent)

> **Subagent prompt:** `references/subagent-prompts.md` → Subagent 1

**Inputs:** connector_name, requested_flows

**What it does:**
1. Verifies connector exists at expected path
2. Reads connector file, lists flows already in `create_all_prerequisites!`
3. Reads tech spec for each requested flow's API details
4. Validates dependencies -- checks each requested flow's prerequisites exist
5. Resolves implementation order (topological sort)

**Outputs:** existing_flows, implementation_order, missing_prerequisites

**Gates (HARD STOP — no exceptions):**
- If tech spec missing → **STOP IMMEDIATELY. Do NOT proceed to Step 2.**
  Tell the user: "No tech spec found for {ConnectorName}. Please either:
  (1) Run the `generate-tech-spec` skill first, or
  (2) Provide the tech spec file manually at `grace/rulesbook/codegen/references/{connector_name}/technical_specification.md`."
  Do NOT attempt to infer API details from existing connector code or any other source.
  A tech spec is mandatory — never skip this requirement.
- If prerequisites missing → STOP, inform user what to add first.

---

### Step 2: Flow Implementation (MANDATORY subagent per flow, sequential)

> **CRITICAL: You MUST delegate each flow to a subagent. Do NOT implement code yourself.**
> Read the subagent prompt from `references/subagent-prompts.md` → Subagent 2, fill in the
> variables ({ConnectorName}, {FlowName}, tech spec path), and spawn a subagent for EACH flow.
> Wait for each subagent to complete before spawning the next.

> **Detailed procedure:** `references/flow-implementation-guide.md`
> **Per-flow patterns:** `references/flow-patterns/{flow}.md`

Implement each flow in the resolved order from Step 1. **Spawn one subagent per flow.**

**Each flow subagent does:**
1. Reads tech spec for this flow's endpoint
2. Reads `references/flow-patterns/{flow}.md`
3. Adds flow to `create_all_prerequisites!`
4. Adds `macro_connector_implementation!` block
5. Creates transformer types + TryFrom impls
6. Adds trait marker implementation
7. Runs `cargo build --package connector-integration`

**Flow type quick reference** (full table in `references/flow-implementation-guide.md`):

| Flow | FlowData | RequestData | ResponseData | T? |
|------|----------|-------------|--------------|-----|
| Authorize | PaymentFlowData | PaymentsAuthorizeData\<T\> | PaymentsResponseData | Yes |
| PSync | PaymentFlowData | PaymentsSyncData | PaymentsResponseData | No |
| Capture | PaymentFlowData | PaymentsCaptureData | PaymentsResponseData | No |
| Void | PaymentFlowData | PaymentVoidData | PaymentsResponseData | No |
| Refund | RefundFlowData | RefundsData | RefundsResponseData | No |
| RSync | RefundFlowData | RefundSyncData | RefundsResponseData | No |

**Trait marker names** (not uniform -- use exact names):

| Flow | Trait |
|------|-------|
| Authorize | `PaymentAuthorizeV2<T>` |
| PSync | `PaymentSyncV2` |
| Capture | `PaymentCapture` |
| Void | `PaymentVoidV2` |
| Refund | `RefundV2` |
| RSync | `RefundSyncV2` |
| SetupMandate | `SetupMandateV2<T>` |
| RepeatPayment | `RepeatPaymentV2<T>` |
| PaymentMethodToken | `PaymentTokenV2<T>` |
| CreateAccessToken | `PaymentAccessToken` |
| CreateOrder | `PaymentOrderCreate` |
| CreateSessionToken | `PaymentSessionToken` |
| CreateConnectorCustomer | `CreateConnectorCustomer` |
| IncomingWebhook | `IncomingWebhook` + `SourceVerification` + `BodyDecoding` |
| AcceptDispute | `AcceptDispute` |
| SubmitEvidence | `SubmitEvidenceV2` |
| DefendDispute | `DisputeDefend` |

---

### Step 3: gRPC Testing (MANDATORY subagent)

> **CRITICAL: You MUST delegate testing to a subagent. Do NOT run grpcurl yourself.**
> **Subagent prompt:** `references/subagent-prompts.md` → Subagent 3
> **Testing guide:** `references/grpc-testing-guide.md`

**Inputs:** connector_name, list of newly added flows

**What it does:**
1. Starts gRPC server
2. Loads credentials from `creds.json`
3. Tests each new flow via grpcurl
4. Validates responses (PASS/FAIL criteria in testing guide)
5. If failed: reads server logs, fixes code, rebuilds, retests (max 7 iterations)

**gRPC service mapping** (full table in testing guide):

| Flow | gRPC Method |
|------|-------------|
| Authorize | `types.PaymentService/Authorize` |
| PSync | `types.PaymentService/Get` |
| Capture | `types.PaymentService/Capture` |
| Void | `types.PaymentService/Void` |
| Refund | `types.PaymentService/Refund` |
| RSync | `types.RefundService/Get` |
| SetupMandate | `types.PaymentService/SetupRecurring` |
| RepeatPayment | `types.RecurringPaymentService/Charge` |

**Gate:** All new flows must pass before proceeding.

---

### Step 4: Quality Review (MANDATORY subagent)

> **CRITICAL: You MUST delegate quality review to a subagent. Do NOT review yourself.**
> **Subagent prompt:** `references/subagent-prompts.md` → Subagent 4
> **Checklist:** `references/quality-checklist.md`

**What it does:**
1. Architecture compliance (no legacy types)
2. Status mapping (no hardcoded statuses)
3. Code quality (no unwrap, descriptive errors)
4. Consistency with existing flows in this connector
5. Final `cargo build`

---

## Supported Flows Catalog

| Category | Flows |
|----------|-------|
| Core | Authorize, PSync, Capture, Void, Refund, RSync |
| Pre-Auth | CreateAccessToken, CreateOrder, CreateConnectorCustomer, PaymentMethodToken, CreateSessionToken |
| Mandate/Recurring | SetupMandate, RepeatPayment, MandateRevoke |
| Dispute | AcceptDispute, SubmitEvidence, DefendDispute |
| Webhook | IncomingWebhook (requires SourceVerification + BodyDecoding traits) |
| Auth | PreAuthenticate, Authenticate, PostAuthenticate |

---

## Reference Index

| Path | Contents |
|------|----------|
| `references/subagent-prompts.md` | Full prompts for all 4 subagents |
| `references/flow-implementation-guide.md` | 3-part procedure, type table (17 flows), per-flow subagent prompt |
| `references/grpc-testing-guide.md` | gRPC service map, grpcurl templates, test validation criteria |
| `references/flow-dependencies.md` | Dependency graph and resolution algorithm |
| `references/macro-reference.md` | Both core macros, parameters, content types, generic rules |
| `references/type-system.md` | Core imports, RouterDataV2, domain_types structure |
| `references/quality-checklist.md` | Pre-submission quality gates |
| `references/utility-functions.md` | Error handling, amount conversion helpers |
| `references/flow-patterns/*.md` | Per-flow: authorize, psync, capture, refund, rsync, void |

---

Source: https://www.openparable.com/skill/development/add-connector-flow (OpenParable). Cite the canonical URL above.
