feat(tools): add Razorpay payment processing integration

[shivamshahi07]

Add Razorpay MCP tool integration for payment processing, invoicing, and refund management. Implements 6 MCP tools:

• razorpay_list_payments: List recent payments with filters (pagination, date range)
• razorpay_get_payment: Fetch detailed payment information by ID
• razorpay_create_payment_link: Create one-time payment links with shareable URLs
• razorpay_list_invoices: List invoices with status and type filtering
• razorpay_get_invoice: Fetch invoice details including line items
• razorpay_create_refund: Create full or partial refunds for payments

Features:

• Authentication via HTTP Basic Auth (RAZORPAY_API_KEY + RAZORPAY_API_SECRET)
• Credential spec in dedicated razorpay.py (follows repo pattern)
• Comprehensive error handling (401, 403, 404, 400, 429, 500, timeouts)
• Input validation (payment IDs, invoice IDs, amounts, currencies)
• Full test coverage (42 unit tests)

Description

This PR adds an MVP Razorpay integration to the hive-tools MCP server, enabling agents to process payments, manage invoices, and handle refunds through Razorpay's payment platform.

The integration implements 6 MCP tools covering the core payment workflows:

• Payment listing and retrieval for transaction monitoring
• Payment link creation for one-time payments
• Invoice management for billing workflows
• Refund processing for customer support scenarios

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)

Related Issues

Fixes #4404

Changes Made

Core Implementation

• Created _RazorpayClient HTTP client with Basic Auth support
• Implemented 6 MCP tools with comprehensive input validation
• Added error mapping for Razorpay API error codes (401, 403, 404, 400, 429, 500)
• Integrated with existing credential management system

Files Added

• tools/src/aden_tools/credentials/razorpay.py - Credential spec with health check
• tools/src/aden_tools/tools/razorpay_tool/razorpay_tool.py - Main implementation (550 lines)
• tools/src/aden_tools/tools/razorpay_tool/__init__.py - Module initialization
• tools/src/aden_tools/tools/razorpay_tool/README.md - Comprehensive tool documentation
• tools/tests/tools/test_razorpay_tool.py - Unit tests (42 tests)

Files Modified

• tools/src/aden_tools/credentials/__init__.py - Register Razorpay credentials
• tools/src/aden_tools/tools/__init__.py - Register Razorpay tools

Testing

• Unit tests pass (42/42 tests passing)
• Lint passes (ruff check - all checks passed)
• Manual testing performed (manual e2e test with Razorpay test-mode credentials - all 6 tools verified)

E2E Test Results

I have verified the Razorpay integration using live test API credentials against Razorpay's test environment.

Dashboard Screenshots:

Payment Links Dashboard:

Razorpay dashboard showing created payment links from integration testing

Invoices Dashboard:

Invoices dashboard showing test invoices used during testing of get_invoices.

Tool Output Example:

IDE output showing clean JSON response from razorpay_get_payment tool

Live Test Logs

All 6 tools successfully tested against Razorpay's test environment. Full verification output (JSON for all 6 tools):

View Complete E2E Test Results (gist link for json)

Verification Summary:

• Authentication and credential management work correctly
• All 6 tools successfully communicate with Razorpay API
• Error handling catches and reports issues appropriately (tested invalid IDs, network errors)
• Payment creation, invoice fetching, and refund processing are fully functional
• Partial refunds work correctly (tested with real test payment)

Credential Setup

Authentication Method: HTTP Basic Auth

• Username: RAZORPAY_API_KEY (Key ID, format: rzp_test_xxxxx)
• Password: RAZORPAY_API_SECRET (Key Secret)

Health Check: GET https://api.razorpay.com/v1/payments?count=1

Get Credentials: https://dashboard.razorpay.com/app/keys

Test Mode: Uses test API keys (rzp_test_*) - no real financial transactions during testing

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Lint passes (cd tools && uv run ruff check .)

Additional Notes

• Follows established patterns from Apollo and HubSpot integrations
• All linter checks passing (ruff with 100-char line limit)
• Uses Razorpay test mode for all development and testing
• Compatible with existing credential management infrastructure
• No breaking changes to existing tools or APIs

[Lumi-artLife]

Impressive comprehensive implementation! 6 tools + 42 tests + full E2E verification shows serious attention to quality.

One question on the payment flow: How does the integration handle async events like payment.captured webhooks? Razorpay sends these for successful payments, and they're crucial for updating payment status in real-time. Is webhook handling planned for a follow-up PR, or is the current polling-based approach (razorpay_get_payment) the intended workflow?

Also curious about the test coverage for edge cases like network timeouts and rate limiting (429s) - the error mapping looks solid but real-world payment APIs can be unpredictable.

Great work on following the existing patterns from Apollo/HubSpot integrations. Consistency across the tool suite really helps with developer experience.

[shivamshahi07]

@Lumi-artLife Thanks for the thoughtful review!

Webhooks: In this PR the intended workflow is polling via razorpay_get_payment / razorpay_list_payments. Webhook handling is scoped out since it would require a persistent listener + event ingestion (outside the current stateless MCP tool model). Happy to explore a webhook/event-driven follow-up if the project wants that.

Timeouts / 429s: Requests use a timeout and 429s are surfaced as retriable tool errors (no infinite retries). The tests cover the error-mapping paths, and I can add a couple more explicit timeout/429 cases if you’d like.