Refunds - Update

Update a refund.

cURL
curl --request POST \
  --url https://sandbox.hyperswitch.io/refunds/{refund_id} \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "reason": "Paid by mistake"
}
'

Endpoint POST /refunds/{refund_id}

Request example (body)

{
  "reason": "Paid by mistake"
}

Response examples

200 OK

{
  "refund_id": "<string>",
  "payment_id": "<string>",
  "amount": 6540,
  "currency": "<string>",
  "status": "succeeded",
  "connector": "stripe",
  "reason": "<string>",
  "metadata": {},
  "error_message": "<string>",
  "error_code": "<string>",
  "unified_code": "<string>",
  "unified_message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "profile_id": "<string>",
  "merchant_connector_id": "<string>",
  "split_refunds": {
    "stripe_split_refund": {
      "revert_platform_fee": true,
      "revert_transfer": true
    }
  },
  "issuer_error_code": "<string>",
  "issuer_error_message": "<string>",
  "raw_connector_response": "<string>"
}

400 Bad Request

Authorization

Header: api-key (string) — required

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Path parameters

  • refund_id (string) — required The identifier for the refund.

Body (application/json)

  • reason (string | null) An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive. Maximum length: 255 Example: "Customer returned the product"

  • metadata (object) Up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Useful for storing additional, structured information on an object.

Response (200 — Refund updated)

Content-Type: application/json

Fields:

  • refund_id (string) — required Unique identifier for the refund.

  • payment_id (string) — required The payment id against which refund is initiated.

  • amount (integer) — required The refund amount in the lowest denomination of the currency (e.g., cents for USD, paisa for INR). Must satisfy x >= 100. Example: 6540

  • currency (string) — required Three-letter ISO currency code.

  • status (enum) — required Refund status. Available options: succeeded, failed, pending, review.

  • connector (string) — required The connector used for the refund and the corresponding payment. Example: "stripe"

  • reason (string | null) Arbitrary string attached to the object.

  • metadata (object) Up to 50 keys; key names up to 40 chars; values up to 500 chars.

  • error_message (string | null) The error message (if any).

  • error_code (string | null) The code for the error (if any).

  • unified_code (string | null) Error code unified across connectors, present if there was an error while calling the connector.

  • unified_message (string | null) Error message unified across connectors, present if there was an error while calling the connector.

  • created_at (string | null) Timestamp when the refund was created.

  • updated_at (string | null) Timestamp when the refund was updated.

  • profile_id (string | null) The id of the business profile for this refund.

  • merchant_connector_id (string | null) The merchant_connector_id of the processor through which this payment went through.

  • split_refunds (object) Charge-specific fields for controlling the revert of funds from either platform or connected account. Check sub-fields for details.

    • Example sub-object shown in response:

      • stripe_split_refund:

        • revert_platform_fee: true

        • revert_transfer: true

    • (Original doc listed "Option 1 / Option 2 / Option 3" as placeholders for possible sub-options.)

  • issuer_error_code (string | null) Error code received from the issuer in case of failed refunds.

  • issuer_error_message (string | null) Error message received from the issuer in case of failed refunds.

  • raw_connector_response (string | null) Contains the whole connector response.

Suggest edits or raise an issue:

  • Edit on GitHub: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/refunds/refunds--update.mdx

  • Raise an issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/refunds/refunds--update

Related:

  • Refunds - Create: https://api-reference.hyperswitch.io/v1/refunds/refunds--create

  • Refunds - Retrieve: https://api-reference.hyperswitch.io/v1/refunds/refunds--retrieve

PreviousPayment Method Session - Delete a saved payment methodNextPayments - Retrieve