Create 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

Name	Type	Description
`order_id`	`string`required	The unique order identifier to refund against.

Request Body

Name	Type	Description
`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.
`order_amount`	`object`required	The refund amount details.
`value`	`integer`required	Refund amount in the smallest currency unit (e.g., paisa for INR). Minimum ₹1 (100 paisa).
`currency`	`string`required	Three-letter ISO 4217 currency code.
`merchant_metadata`	`object`	Arbitrary key-value pairs for merchant use. Maximum 10 pairs, 256 characters each.
`products`	`object[]`	Array of product objects for IMEI blocking (required for partial refunds with IMEI).
`product_code`	`string`	Product code/SKU.
`imei_number`	`string`	IMEI number to block for partial refunds.
`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`	Customer information.
`email_id`	`string`	Customer's email address.
`first_name`	`string`	Customer's first name.
`last_name`	`string`	Customer's last name.
`customer_id`	`string`	Unique identifier of the customer.
`mobile_number`	`string`	Customer's mobile number.
`country_code`	`string`	Country code of the registered mobile number. Defaults to 91.
`billing_address`	`object`	Physical address.
`shipping_address`	`object`	Physical address.
`is_edit_customer_details_allowed`	`boolean`	Whether the customer is allowed to edit their details.
`split_info`	`object`	Split settlement information for refunds involving split payments.
`split_type`	`string`	Type of split.
`split_details`	`object[]`

Response

Name	Type	Description
`data`	`object`
`order_id`	`string`	Unique identifier of the refund order.
`parent_order_id`	`string`	Unique identifier of the parent order being refunded.
`merchant_order_reference`	`string`	Merchant reference for the refund.
`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`
`purchase_details`	`object`
`payments`	`PaymentObject[]`
`created_at`	`string`	ISO 8601 UTC timestamp when the refund was created.
`updated_at`	`string`	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:

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"
  }
}'

Run this request

Bearer token

Path parameters

order_id

Request body (JSON)

Status:

200 OK

{
  "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"
  }
}