Razorpay

​

What this connector does

​

Why it’s different from the other four connectors on this site

​

The three pieces

1. Refund creation. Your server calls POST /execute with a razorpay-refund policy reference. If the policy approves, the connector calls Razorpay’s refund-create API.
2. Webhook receipt. Razorpay calls back to POST /webhooks/razorpay when the refund’s status changes. This milestone stops at verifying the signature and durably recording the event, it does not yet act on it. See Verify Razorpay webhooks.
3. Settlement confirmation. A background poll loop picks up the recorded event, fetches the refund’s real status directly from Razorpay (never trusting the webhook’s own claimed event type), and appends a signed SettlementConfirmation to the Execution Trust Record. See Settlement.

​

Requesting a refund

import { RazorpayRefundService } from "@parmana/connector-sdk";

const outcome = await refundService.requestRefund({
  businessTransactionId: "eed2a972-1bf5-4166-8472-761f76fbf1b2",
  paymentId: "pay_XYZ789",
  amountPaise: 100,          // omit for a full refund of the remaining refundable amount
  reason: "Customer requested refund",
  scopeId: "customer-42",    // groups requests under the daily cumulative cap
});

console.log(outcome.receipt.approved, outcome.receipt.razorpayRefundId, outcome.replayed);

​

The reference policy

​

Try it without touching Razorpay at all

npx tsx examples/tutorials/61-razorpay-refund/run.ts

==================================================
Tutorial 61 - Razorpay Refund Connector
==================================================

Outcome 1 - Approved and Executed
--------------------------------------------------
Approved         : true
Razorpay Refund  : rfnd_b5e7e281c6cb7b
Amount (paise)   : 250000
Policy Reason    : Refund authorized. Payment status, currency, refundable remainder, per-refund cap, and daily cumulative cap requirements were satisfied.
Key ID (redacted): rzp_test...

Outcome 2 - Denied by Policy
--------------------------------------------------
Approved      : false
Matched Rule  : reject-payment-not-captured
Reason        : Refund rejected because the payment status is not captured.

Outcome 3 - Replay Returns Recorded Result
--------------------------------------------------
Replayed              : true
Same Refund Returned  : true
Refunds On Razorpay   : 1 (unchanged from 1)

Outcome 4 - Tamper Rejected
--------------------------------------------------
Rejected      : true
Reason        : Execution Gateway rejected request: failed checks [businessTransactionHashMatches, nonceUnseen]. businessTransactionHash mismatch: expected 475f50869e44bded75ef1c152ba1f8cb5c5cd1e0ddba48b79cb573664a05c878, got 844d9307d40ebd22245894767ceddd8052c31f535a70b4ff27358254bf10a78f.

==================================================
Tutorial completed successfully.
==================================================

​

Configuration

​

What’s proven where, precisely

• packages/api/tests/integration/razorpay-refund.integration.test.ts and razorpay-settlement.integration.test.ts hit MockRazorpayServer, not the real network. They run on every npm test, no gate required.
• packages/api/tests/integration/razorpay-real-webhook-fixture.integration.test.ts always runs too, it replays a real, captured Razorpay-delivered webhook payload (redacted for PII) through the live route code, no live network call, but real captured bytes, not a synthetic fixture.
• packages/api/tests/integration/razorpay-live.integration.test.ts is the only test in this codebase that calls a real Razorpay endpoint. It is gated behind ALLOW_LIVE_RAZORPAY=1 plus real RAZORPAY_TEST_KEY_ID / RAZORPAY_TEST_KEY_SECRET credentials (which must start with rzp_test_, or the suite aborts before any network call), and does not run in a default npm test. Even fully enabled, this suite only proves Razorpay test-mode reachability and money movement, one ₹1.00 (100 paise) refund against a manually captured test-mode payment, never live-mode.
• True live-mode operation (real money, real bank settlement) is proven once, manually, against a permanent production deployment, not by the automated test suite: one authenticated, policy-gated 100-paise refund against a real, card-paid ₹10 Payment Link, producing a genuine refund.processed webhook from Razorpay’s own infrastructure and a signed SETTLED settlement confirmation roughly 43 seconds later. This validates one real-money transaction end to end, not sustained live-mode operation, volume, or failover. See docs/CLAIMS.md §3.9 for the full trace.

​

[FUTURE]

• RazorpayX payouts. No implementation exists. This connector covers refund creation only.
• A general-purpose way to add a new external connector. Adding anything beyond Razorpay and the four reference mocks means editing bootstrap code today, see Add a connector.

​

Next