> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integrations/prism/api-reference/refund.md). # Refund ## Overview The `Refund` RPC returns funds to a customer's payment method after the original payment has been captured and settled. This is the standard way to handle returns, cancellations after fulfillment, or service adjustments in e-commerce and retail businesses. **Business Use Case:** When a customer returns a product, cancels a service after delivery, or disputes a charge that you choose to honor. Refunds reverse the money flow, returning captured funds to the customer's payment method. This is different from voids or reverses which prevent or undo charges before settlement. ## Purpose **Why use Refund?** | Scenario | Developer Implementation | | -------------------------------- | --------------------------------------------------------------------------------------------------------- | | **Product returns** | Customer returns merchandise - call `Refund` with the original `connector_transaction_id` to return funds | | **Post-settlement cancellation** | Service cancelled after delivery - call `Refund` to compensate customer for unused service | | **Customer satisfaction** | Partial refund for service issues - call `Refund` with partial amount to maintain customer relationship | | **Duplicate charges** | Settled duplicate transaction - call `Refund` to return extra charges after settlement | | **Fraud goodwill** | Goodwill refund for unauthorized use - call `Refund` to resolve dispute amicably | **Key outcomes:** * Funds returned to customer's payment method (typically 5-10 business days) * Refund appears as separate transaction on customer's statement * Original payment remains captured and settled * Refund status tracked separately from original payment * Can be partial (less than original amount) or full ## Request Fields | Field | Type | Required | Description | | -------------------------- | ------------------ | -------- | ------------------------------------------------------------------------- | | `merchant_refund_id` | string | Yes | Your unique identifier for this refund operation | | `connector_transaction_id` | string | Yes | The connector's transaction ID from the original authorization | | `payment_amount` | int64 | Yes | Original payment amount in minor units | | `refund_amount` | Money | Yes | Amount to refund (can be partial or full) | | `reason` | string | No | Reason for the refund | | `webhook_url` | string | No | URL for webhook notifications | | `merchant_account_id` | string | No | Merchant account ID for the refund | | `capture_method` | CaptureMethod | No | Capture method related to the original payment. Values: MANUAL, AUTOMATIC | | `metadata` | SecretString | No | Metadata specific to the connector | | `refund_metadata` | SecretString | No | Metadata specific to the refund | | `connector_feature_data` | SecretString | No | Connector-specific metadata for the transaction | | `browser_info` | BrowserInformation | No | Browser information, if relevant | | `state` | ConnectorState | No | State data for access token storage and other connector-specific state | | `test_mode` | bool | No | Process as test transaction | | `payment_method_type` | PaymentMethodType | No | Indicates the sub type of payment method | | `customer_id` | string | No | Merchant's customer ID | ## Response Fields | Field | Type | Description | | --------------------- | -------------------- | ---------------------------------------------------------------- | | `merchant_refund_id` | string | Your refund reference (echoed back) | | `connector_refund_id` | string | Connector's ID for the refund | | `status` | RefundStatus | Current status of the refund. Values: PENDING, SUCCEEDED, FAILED | | `error` | ErrorInfo | Error details if refund failed | | `status_code` | uint32 | HTTP status code from the connector | | `response_headers` | map\ | Optional HTTP response headers from the connector | | `refund_amount` | Money | Amount being refunded | | `payment_amount` | int64 | Original payment amount | | `refund_reason` | string | Reason for the refund | | `created_at` | int64 | Unix timestamp when the refund was created | | `updated_at` | int64 | Unix timestamp when the refund was last updated | | `processed_at` | int64 | Unix timestamp when the refund was processed | ## Example ### Request (grpcurl) ```bash grpcurl -H "x-connector: stripe" \ -H "x-connector-config: {\"config\":{\"Stripe\":{\"api_key\":\"$STRIPE_API_KEY\"}}}" \ -d '{ "merchant_refund_id": "refund_001", "connector_transaction_id": "pi_3Oxxx...", "payment_amount": 1000, "refund_amount": { "minor_amount": 1000, "currency": "USD" }, "reason": "Customer returned item", "test_mode": true }' \ localhost:8080 \ types.PaymentService/Refund ``` ### Response ```json { "merchant_refund_id": "refund_001", "connector_refund_id": "re_3Oxxx...", "status": "SUCCEEDED", "status_code": 200, "refund_amount": { "minor_amount": 1000, "currency": "USD" }, "payment_amount": 1000, "refund_reason": "Customer returned item", "created_at": 1709577600, "updated_at": 1709577600 } ``` ## Next Steps * [Capture](/integrations/prism/api-reference/capture.md) - Finalize a payment before refunding * [Get](/integrations/prism/api-reference/get.md) - Check original payment status before refunding * [Void](/integrations/prism/api-reference/void.md) - Cancel before capture (faster than refund) * [Refund Service](/integrations/prism/api-reference/refund-service.md) - Additional refund operations --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hyperswitch.io/integrations/prism/api-reference/refund.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.