Create a Payment Refund

POST/api/pay/v1/refunds/{order_id}

Creates a refund against a completed order.

Important notes:

For a full refund, all IMEI numbers associated with products are automatically blocked.
For a partial refund, you must specify the IMEI number that needs to be blocked.
Refunds of less than ₹1 are not supported.
For a given day, the total sale amount must be greater than or equal to the total refund amount.

Brand Wallet refunds: Set destination to WALLET and include the customer object with customer_id to refund directly into the customer's brand wallet.

View as Markdown Open in ChatGPT Open in Claude Open in Perplexity

Requires Bearer token. Get token →

Path Parameters

Field	Details
`order_id` `string`required	The unique order identifier to refund against. Constraints Maximum length: 50 characters

Header Parameters

Field	Details
`Request-Timestamp` `string`date-time	ISO 8601 UTC timestamp of the request. Used for idempotency and audit.
`Request-ID` `string`	Use a global unique identifier [GUID] for the request. Constraints Minimum length: 1 characterMaximum length: 50 characters

Request Bodyrequired

Field	Details
`merchant_order_reference` `string`required	Idempotency Key. Unique identifier for the refund request. Duplicate requests with the same `merchant_order_reference` will return the existing refund instead of creating a new one. Constraints Minimum length: 1 characterMaximum length: 50 characters
`order_amount` `object`required2 nested fields	The refund amount details.
`merchant_metadata` `object`	Arbitrary key-value pairs for merchant use. Maximum 10 pairs, 256 characters each. Constraints Maximum properties: 10 Additional properties: string · Maximum length: 256 characters
`products` `object[]`2 nested fields	Array of product objects for IMEI blocking (required for partial refunds with IMEI).
`destination` `string`	Where to send the refund: `SOURCE` — Refund to the original payment source (default) `WALLET` — Refund to the customer's brand wallet (requires `customer.customer_id`) Allowed values: `SOURCEWALLET`
`customer` `object`9 nested fields	Required when destination is WALLET. Must include customer_id.
`split_info` `object`2 nested fields	Split settlement information for refunds involving split payments.

Response

Field	Details
`data` `object`13 nested fields
`order_id` `string`	Unique identifier of the refund order. Constraints Maximum length: 50 characters
`parent_order_id` `string`	Unique identifier of the parent order being refunded. Constraints Maximum length: 50 characters
`merchant_order_reference` `string`	Merchant reference for the refund. Constraints Minimum length: 1 characterMaximum length: 50 characters
`type` `string`	Payment type. Allowed values: `CHARGEREFUND`
`status` `string`	Refund status. Allowed values: `CREATEDPENDINGPROCESSEDFAILED`
`merchant_id` `string`	Unique identifier of the merchant.
`order_amount` `object`2 nested fields
`purchase_details` `object`3 nested fields
`payments` `PaymentObject[]`8 nested fields
`created_at` `string`date-time	ISO 8601 UTC timestamp when the refund was created.
`updated_at` `string`date-time	ISO 8601 UTC timestamp when the refund was last updated.
`integration_mode` `string`	Mode of implementation. Allowed values: `SEAMLESSREDIRECT`
`payment_retries_remaining` `integer`	Remaining payment retry attempts.

Status Codes

`200`	Refund created successfully.
`400`	The request was malformed or missing required fields.
`401`	Authentication failed — missing, expired, or invalid Bearer token.
`404`	The requested resource does not exist.
`422`	Unprocessable Entity — amount limit exceeded or invalid refund.
`500`	An unexpected error occurred on the server.

Example:

Run

Request

curl -X POST "https://api.pluralpay.in/api/pay/v1/refunds/{order_id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "merchant_order_reference": "e436fefa-f0e9-4b36-ac01-3d158c31726c",
  "order_amount": {
    "value": 400,
    "currency": "INR"
  },
  "merchant_metadata": {
    "key1": "XX",
    "key2": "DOF"
  }
}'

Status:

{
  "data": {
    "order_id": "v1-241010071949-aa-vcqtJY",
    "parent_order_id": "v1-241010055924-aa-AHbN0s",
    "merchant_order_reference": "e436fefa-f0e9-4b36-ac01-3d158c31726c",
    "type": "REFUND",
    "status": "PROCESSED",
    "merchant_id": "108272",
    "order_amount": {
      "value": 400,
      "currency": "INR"
    },
    "purchase_details": {
      "customer": {
        "email_id": "[email protected]",
        "first_name": "Kevin",
        "last_name": "Bob",
        "customer_id": "123456",
        "mobile_number": "9876543210",
        "country_code": "91"
      },
      "merchant_metadata": {
        "key1": "XX",
        "key2": "DOF"
      }
    },
    "payments": [
      {
        "id": "v1-241010071949-aa-vcqtJY-cc-b",
        "status": "PROCESSED",
        "payment_amount": {
          "value": 400,
          "currency": "INR"
        },
        "payment_method": "CARD",
        "acquirer_data": {
          "approval_code": "",
          "acquirer_reference": "7285447904236780703954",
          "rrn": "",
          "is_aggregator": true
        },
        "created_at": "2024-10-10T07:19:49.423Z",
        "updated_at": "2024-10-10T07:19:51.205Z"
      }
    ],
    "created_at": "2024-10-10T07:19:49.424Z",
    "updated_at": "2024-10-10T07:19:51.205Z"
  }
}