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

# Refunds

> Issue refunds for payments

A refund sends the original payment amount back to the customer's Stellar wallet. Refunds are processed on-chain and reflect a `succeeded` or `failed` status once the transaction settles.

## The refund object

<ResponseField name="id" type="string">
  Unique identifier. Prefixed with `rf_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"refund"`.
</ResponseField>

<ResponseField name="payment_id" type="string">
  The payment being refunded.
</ResponseField>

<ResponseField name="customer_id" type="string">
  The customer receiving the refund.
</ResponseField>

<ResponseField name="amount" type="string">
  Amount refunded, e.g. `"50 XLM"`.
</ResponseField>

<ResponseField name="status" type="string">
  `pending`, `succeeded`, or `failed`.
</ResponseField>

<ResponseField name="reason" type="string">
  Optional reason for the refund.
</ResponseField>

<ResponseField name="receiver_wallet_address" type="string">
  Stellar public key the refund was sent to.
</ResponseField>

<ResponseField name="metadata" type="object">
  Arbitrary key-value data.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

***

## Create a refund

`POST /refunds`

Refunds the full amount of a payment to the customer's wallet on file. Pass `wallet_address` to override the destination.

```bash theme={null}
curl https://api.stellartools.dev/refunds \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_01jx...",
    "reason": "Customer request"
  }'
```

### Body

<ParamField body="payment_id" type="string" required>
  ID of the payment to refund.
</ParamField>

<ParamField body="reason" type="string">
  Reason for the refund.
</ParamField>

<ParamField body="wallet_address" type="string">
  Override the refund destination. Defaults to the wallet that made the original payment.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value data.
</ParamField>