> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refund Payment

> Create a full or partial refund for a payment

<Note>
  This endpoint creates a refund for a captured payment. Refunds can be partial or full amount.
</Note>

## Authentication

This endpoint requires a valid API key with `payments:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="id" type="string" required>
  The payment ID to refund
</ParamField>

## Request Body

<ParamField body="amount" type="integer">
  Amount to refund in cents (defaults to full payment amount)
</ParamField>

<ParamField body="reason" type="string" required>
  Refund reason: "duplicate", "fraudulent", "requested\_by\_customer", "defective", "other"
</ParamField>

<ParamField body="notes" type="string">
  Internal notes about the refund
</ParamField>

<ParamField body="notify_customer" type="boolean">
  Whether to send refund notification email (default: true)
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for the refund
</ParamField>

### Response

Returns the refund object.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/payments/pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/refund' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "amount": 5000,
      "reason": "requested_by_customer",
      "notes": "Customer returned item"
  }'
  ```

  ```javascript Node.js theme={null}
  const refund = await stateset.payments.refund(
    'pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    {
      amount: 5000,
      reason: "requested_by_customer",
      notes: "Customer returned item"
    }
  );
  ```

  ```python Python theme={null}
  refund = stateset.payments.refund(
    'pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    amount=5000,
    reason="requested_by_customer",
    notes="Customer returned item"
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "ref_1234567890abcdef",
    "object": "refund",
    "amount": 5000,
    "currency": "USD",
    "payment_id": "pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "status": "succeeded",
    "reason": "requested_by_customer",
    "notes": "Customer returned item",
    "created_at": "2024-01-20T10:00:00Z",
    "processed_at": "2024-01-20T10:00:05Z",
    "payment": {
      "id": "pay_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
      "amount": 15000,
      "amount_refunded": 5000,
      "refunds_count": 1
    },
    "processor_refund_id": "re_1234567890",
    "receipt_url": "https://receipts.stateset.com/ref_1234567890abcdef",
    "metadata": {
      "return_id": "ret_abc123"
    }
  }
  ```
</ResponseExample>