[livinalt]

What this PR does

• Implements the complete Instamojo payment gateway integration for the AgenticPay platform (Build Instamojo gateway integration #959).
• Adds a dedicated InstamojoClient to communicate with the Instamojo API v1.1, supporting:
  • Payment request creation
  • Payment status retrieval
  • Refund processing
  • HMAC-SHA1 webhook signature verification
• Adds InstamojoGatewayAdapter, extending BaseGatewayAdapter with:
  • Circuit-breaker protection
  • Latency tracking
  • Health check monitoring
• Introduces InstamojoPaymentProvider implementing PaymentProvider for seamless integration with the payment provider registry.
• Updates payment routing to automatically select Instamojo for INR currency transactions and the instamojo payment network.
• Registers Instamojo in the default payment provider bootstrap process.
• Adds REST API endpoints under /api/v1/instamojo for payment requests, payment retrieval, refunds, and webhook processing.
• Mounts the Instamojo router into the Express application.
• Adds comprehensive unit and integration tests covering successful flows, failure scenarios, webhook validation, provider execution, and routing.
• Breaking changes: None.
• Migrations: None required.

---

Changes

New Files

• backend/src/integrations/instamojo/types.ts

  • TypeScript interfaces for payment requests, payments, refunds, webhook payloads, and configuration.

• backend/src/integrations/instamojo/instamojo-client.ts

  • Instamojo API client responsible for HTTP communication, credential management, webhook verification, and sandbox simulation.

• backend/src/integrations/instamojo/gateway-adapter.ts

  • InstamojoGatewayAdapter implementation extending BaseGatewayAdapter.

• backend/src/integrations/instamojo/index.ts

  • Barrel exports for the Instamojo integration module.

• backend/src/integrations/instamojo/__tests__/instamojo.test.ts

  • Unit tests covering the Instamojo client and gateway adapter.

• backend/src/services/payments/providers/instamojo.ts

  • Instamojo implementation of the PaymentProvider interface.

• backend/src/services/payments/__tests__/instamojo-provider.test.ts

  • Integration tests covering provider execution and routing.

• backend/src/routes/instamojo.ts

  • REST API endpoints for payment requests, payments, refunds, and webhook handling.

Updated Components

• backend/src/integrations/gateway-adapter.ts

  • Added 'instamojo' to the GatewayType union.

• backend/src/services/payments/payment-router.ts

  • Updated selectProviderId to support INR transactions and the instamojo network.

• backend/src/services/payments/bootstrap.ts

  • Registered InstamojoPaymentProvider during application startup.

• backend/src/index.ts

  • Mounted instamojoRouter under /api/v1/instamojo.

• backend/src/config/env.ts

  • Added default environment fallbacks for test execution.

• backend/src/config/database.ts

  • Updated readReplicaRouter initialization to avoid module initialization race conditions during testing.

---

Why

This PR implements the Instamojo payment gateway integration requested in Issue #959, enabling AgenticPay to process payments in Indian Rupees (INR) through the Instamojo payment platform.

The implementation integrates with the existing payment provider registry and gateway abstraction layer, supports secure webhook verification, includes circuit-breaker and health monitoring capabilities, and provides sandbox simulation when live API credentials are unavailable, ensuring reliable local development and CI execution.

---

How to test

1. Run the Instamojo client and gateway adapter tests:

npx --no-install vitest run backend/src/integrations/instamojo/__tests__/instamojo.test.ts

2. Run the Instamojo payment provider and routing tests:

npx --no-install vitest run backend/src/services/payments/__tests__/instamojo-provider.test.ts

3. (Optional) Configure the following environment variables for live Instamojo integration:

• INSTAMOJO_API_KEY
• INSTAMOJO_AUTH_TOKEN
• INSTAMOJO_PRIVATE_SALT
• INSTAMOJO_SANDBOX (true for sandbox, false for production)

4. Test the REST API endpoints:

• POST /api/v1/instamojo/payment-requests
• GET /api/v1/instamojo/payment-requests/:id
• GET /api/v1/instamojo/payments/:id
• POST /api/v1/instamojo/refunds
• POST /api/v1/instamojo/webhook

---

Notes

• When Instamojo API credentials are not configured, the client automatically falls back to sandbox/mock mode, allowing local development and automated tests to run without external dependencies.
• Webhook signature verification follows Instamojo's HMAC-SHA1 specification using sorted, pipe-separated field values.
• Existing payment providers and routing behavior remain unchanged.
• Closes Build Instamojo gateway integration #959

[vercel]

@livinalt is attempting to deploy a commit to the smartdevs17's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@livinalt Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits