OpenParable
Skip to content
← Back to skills

New Connector

Development
new-connector

New Connector 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.

Implements a new payment connector from scratch in the connector-service (UCS) Rust codebase. Creates connector foundation and implements all 6 core payment flows (Authorize, PSync, Capture, Refund, RSync, Void). Use when integrating a new payment gateway that does not yet exist. Requires a technical specification at grace/rulesbook/codegen/references/{connector_name}/technical_specification.md.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/juspay/hyperswitch-prism/blob/HEAD/.skills/new-connector/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/new-connector, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

New Connector Implementation

Overview

This skill produces a complete payment connector in the UCS Rust codebase.

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.

Output:

  • Main connector file with macro-based flow implementations
  • Transformers module with request/response types and conversions
  • Registration in the connector registry
  • All 6 core flows + any required pre-auth flows
  • gRPC tested end-to-end

Prerequisites:

  • Tech spec at grace/rulesbook/codegen/references/{connector_name}/technical_specification.md
  • Rust toolchain with cargo

Project Structure

PurposePath
Main connector filecrates/integrations/connector-integration/src/connectors/{connector_name}.rs
Transformers modulecrates/integrations/connector-integration/src/connectors/{connector_name}/transformers.rs
Connector registrycrates/integrations/connector-integration/src/connectors.rs
Enum definitionscrates/common/common_enums/src/enums.rs
Domain utilitiescrates/types-traits/domain_types/src/utils.rs
Macro definitionscrates/integrations/connector-integration/src/connectors/macros/

Critical Conventions

These rules apply to ALL subagents. Include them in every subagent prompt.

  • Use RouterDataV2 (NEVER RouterData), ConnectorIntegrationV2 (NEVER ConnectorIntegration)
  • Import from domain_types (NEVER hyperswitch_domain_models)
  • Connector struct MUST be generic: ConnectorName<T>
  • NEVER hardcode status values -- always map from connector response via From/TryFrom
  • Use macros (create_all_prerequisites! + macro_connector_implementation!) for all flows
  • Check references/utility-functions.md before implementing custom helpers
  • No unwrap(), no fields hardcoded to None, no unnecessary .clone()
  • Auth data accessed via req.connector_config (NOT connector_auth_type)

Workflow: Orchestrator Sequence

Each step below is an independent subagent. The orchestrator delegates each step, waits for completion, and passes outputs to the next step.

Full subagent prompts: references/subagent-prompts.md

Step 1: Tech Spec Validation (Subagent)

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

Inputs: connector_name

What it does:

  • Reads the tech spec
  • Extracts: name, base_url, auth method, amount format, content type
  • Lists all supported flows with HTTP methods and endpoints
  • Detects pre-auth flows:
Pre-Auth FlowDetect when...
CreateAccessTokenOAuth/token auth (POST /login, /oauth/token)
CreateOrderOrder/intent required before payment
CreateConnectorCustomerCustomer object required before payment
PaymentMethodTokenTokenization required before authorize
CreateSessionTokenSession init required before payment

Outputs: connector config, list of flows, list of pre-auth flows

Gate (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 any other source. A tech spec is mandatory.


Step 2: Foundation Setup (Subagent)

Subagent prompt: references/subagent-prompts.md → Subagent 2

Inputs: connector_name, base_url, auth_method, amount_type (from Step 1)

What it does:

  • Runs scripts/add_connector.sh {connector_name} {base_url} --force -y
  • Verifies cargo build --package connector-integration passes
  • Checks UCS conventions (RouterDataV2, generic struct, domain_types imports)
  • Sets up create_amount_converter_wrapper! macro
  • Implements ConnectorCommon trait (id, content_type, base_url, auth_header, error_response)
  • Adds required trait markers (ConnectorServiceTrait, SourceVerification, BodyDecoding)

Outputs: scaffold created, build passing, files list

Gate: Build must pass before proceeding.


Step 3: 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 3, 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 Macro reference: references/macro-reference.md

Execution order (strict sequential — spawn one subagent per flow, wait for completion):

  1. Pre-auth flows (only if detected in Step 1): CreateAccessToken → CreateOrder → CreateConnectorCustomer → PaymentMethodToken → CreateSessionToken

  2. Core flows (always): Authorize → PSync → Capture → Refund → RSync → Void

Each flow subagent does:

  1. Reads tech spec for this flow's endpoint details
  2. Reads references/flow-patterns/{flow}.md for patterns
  3. Adds flow to create_all_prerequisites! with correct types
  4. Adds macro_connector_implementation! block
  5. Creates request/response types + TryFrom impls in transformers.rs
  6. Adds trait marker implementation
  7. Runs cargo build --package connector-integration
  8. Reports SUCCESS or FAILED

Key type reference (full table in references/flow-implementation-guide.md):

FlowFlowDataRequestDataResponseDataT?
AuthorizePaymentFlowDataPaymentsAuthorizeData<T>PaymentsResponseDataYes
PSyncPaymentFlowDataPaymentsSyncDataPaymentsResponseDataNo
CapturePaymentFlowDataPaymentsCaptureDataPaymentsResponseDataNo
VoidPaymentFlowDataPaymentVoidDataPaymentsResponseDataNo
RefundRefundFlowDataRefundsDataRefundsResponseDataNo
RSyncRefundFlowDataRefundSyncDataRefundsResponseDataNo

Step 4: gRPC Testing (MANDATORY subagent)

CRITICAL: You MUST delegate testing to a subagent. Do NOT run grpcurl yourself. Subagent prompt: references/subagent-prompts.md → Subagent 4 Full testing guide: references/grpc-testing-guide.md

Inputs: connector_name, list of implemented flows, creds.json

What it does:

  1. Starts gRPC server (cargo run --bin grpc-server)
  2. Loads credentials from creds.json
  3. Tests each flow via grpcurl against the correct service/method
  4. Validates: status 2xx, no errors, correct status value
  5. If test fails: reads server logs, fixes code, rebuilds, retests

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

FlowgRPC Method
Authorizetypes.PaymentService/Authorize
PSynctypes.PaymentService/Get
Capturetypes.PaymentService/Capture
Voidtypes.PaymentService/Void
Refundtypes.PaymentService/Refund
RSynctypes.RefundService/Get

Anti-loop safeguards: 3-strike rule, max 7 iterations, must change code between retries.

Gate: All flows must pass before proceeding.


Step 5: Quality Review (MANDATORY subagent)

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

What it does:

  1. Architecture compliance: no RouterData (non-V2), no hyperswitch_domain_models
  2. Status mapping: no hardcoded statuses outside match arms
  3. Code quality: no unwrap(), no None-hardcoded fields, descriptive errors
  4. Macro completeness: every flow in both macros + trait markers
  5. Naming conventions: {ConnectorName}{Flow}Request/Response pattern
  6. Final build: cargo build --package connector-integration

Outputs: PASS with 0 violations, or FAIL with list of violations to fix.


Reference Index

PathContents
references/subagent-prompts.mdFull copy-paste prompts for all 5 subagents
references/flow-implementation-guide.md3-part flow procedure, type table (17 flows), per-flow subagent prompt
references/grpc-testing-guide.mdgRPC service map, grpcurl templates, test validation, testing subagent prompt
references/macro-reference.mdBoth core macros, parameters, content types, generic rules
references/type-system.mdCore imports, type paths, domain_types module structure
references/utility-functions.mdError handling, card formatting, amount conversion helpers
references/quality-checklist.mdPre-submission checklist, common mistakes
references/flow-patterns/*.mdPer-flow: authorize, psync, capture, refund, rsync, void
scripts/add_connector.shScaffold script that generates initial connector files