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

# Payment Refund

> A payment refund is a process of returning funds to a customer after a transaction has been completed.

This endpoint allows you to create a refund for a payment. You can specify the amount to be refunded, the reason for the refund, payment\_id and unique reference.

## Refund Statuses

| Status       | Description         |
| ------------ | ------------------- |
| `successful` | A successful refund |
| `pending`    | A pending refund    |
| `failed`     | A failed refund     |

***

## Refund Response Object

```json theme={null}
{
    "id": "refund_1234567890",
    "reference": "refund_001",
    "payment_intent_action_id": "pay_1234567890",
    "amount": 5000,
    "currency": "USD",
    "refund_reason": "Customer requested a refund",
    "status": "pending",
    "status_reason": null,
    "account_id": "acc_1234567890",
    "entity_id": "ent_1234567890",
    "created": 1700000000000
}
```

<ResponseField name="id" type="string">
  Refund record identifier
</ResponseField>

<ResponseField name="reference" type="string">
  Client-provided unique refund reference. Length between 1 and 100 characters.
</ResponseField>

<ResponseField name="payment_intent_action_id" type="string">
  Identifier of the original payment action
</ResponseField>

<ResponseField name="amount" type="number">
  Refund amount
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 three-letter currency code of the original payment
</ResponseField>

<ResponseField name="refund_reason" type="string" optional>
  Reason provided for issuing the refund. Maximum length of 100 characters.
</ResponseField>

<ResponseField name="status" type="string">
  Current refund processing status (pending|successful|failed)
</ResponseField>

<ResponseField name="status_reason" type="string" optional>
  Explanation for the current status
</ResponseField>

<ResponseField name="account_id" type="string">
  Account associated with the refund
</ResponseField>

<ResponseField name="entity_id" type="string">
  Owning entity identifier
</ResponseField>

<ResponseField name="created" type="number">
  The Unix timestamp in milliseconds indicating the creation time
</ResponseField>

***

## Create a Payment Refund

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/refunds \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_intent_action_id": "pay_1234567890",
      "reference": "refund_001",
      "reason": "Customer requested a refund",
      "amount": 5000
    }'
  ```
</CodeGroup>

## Request Fields

<ResponseField name="payment_intent_action_id" type="string">
  Identifier of the payment intent action to be refunded
</ResponseField>

<ResponseField name="reference" type="string">
  Client-provided unique reference for the refund request. Length between 1 and 100 characters.
</ResponseField>

<ResponseField name="reason" type="string" optional>
  Optional reason for requesting the refund. Maximum length of 100 characters.
</ResponseField>

<ResponseField name="amount" type="number">
  Amount to refund; must be greater than zero
</ResponseField>

## Response

<CodeGroup>
  ```json 200 OK lines icon="circle-check" expandable theme={null}
  {
    "status": "success",
    "message": "Refund created successfully",
    "data": {
      "id": "refund_1234567890",
      "reference": "refund_001",
      "payment_intent_action_id": "pay_1234567890",
      "amount": 5000,
      "currency": "USD",
      "refund_reason": "Customer requested a refund",
      "status": "pending",
      "status_reason": null,
      "account_id": "acc_1234567890",
      "entity_id": "ent_1234567890",
      "created": 1700000000000
    }
  }
  ```

  ```json 400-500 lines icon="circle-check" expandable theme={null}
  {
    "status": "error",
    "message": "Invalid refund request",
    "details": {
      "payment_intent_action_id": "Payment intent action ID is required",
      "amount": "Amount must be greater than zero"
    }
  }
  ```
</CodeGroup>

## Retrieve Payment Refunds

Returns paginated list of payment refunds with optional filtering by status, reference, currency, date range, account\_id and entity\_id.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.nuvion.dev/refunds \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -d status=pending \
    -d limit=20 \
    -d reference=refund_001 \
    -d currency=USD \
    -d date_from=2024-01-01T00:00:00Z \
    -d date_to=2024-12-31T23:59:59Z \
    -d prev_cursor=abc123 \
    -d next_cursor=def456 \
    -d account_id=acc_1234567890 \
    -d entity_id=ent_1234567890

  ```
</CodeGroup>

## Query Parameters

<ResponseField name="status" type="string" optional>
  Filter payment refunds by status (pending|successful|failed)
</ResponseField>

<ResponseField name="reference" type="string" optional>
  Filter payment refunds by client-provided reference identifier
</ResponseField>

<ResponseField name="currency" type="string" optional>
  Filter payment refunds by ISO currency code (e.g. USD)
</ResponseField>

<ResponseField name="date_from" type="string" optional>
  Start date for filtering refunds (ISO 8601 format or Unix timestamp in milliseconds)
</ResponseField>

<ResponseField name="date_to" type="string" optional>
  End date for filtering refunds (ISO 8601 format or Unix timestamp in milliseconds)
</ResponseField>

<ResponseField name="prev_cursor" type="string" optional>
  Cursor for fetching the previous page of results
</ResponseField>

<ResponseField name="next_cursor" type="string" optional>
  Cursor for fetching the next page of results
</ResponseField>

<ResponseField name="limit" type="number" optional>
  Number of records to return per page (default: 20, max: 100)
</ResponseField>

<ResponseField name="account_id" type="string" optional>
  ULID of the account to filter payment refunds
</ResponseField>

<ResponseField name="entity_id" type="string" optional>
  ULID of the entity to filter payment refunds
</ResponseField>

## Response

<CodeGroup>
  ```json 200 OK lines icon="circle-check" expandable theme={null}
  {
    "status": "success",
    "message": "Refunds retrieved successfully",
    "data": {
      "items": [
        {
          "id": "refund_1234567890",
          "reference": "refund_001",
          "payment_intent_action_id": "pay_1234567890",
          "amount": 5000,
          "currency": "USD",
          "refund_reason": "Customer requested a refund",
          "status": "pending",
          "status_reason": null,
          "account_id": "acc_1234567890",
          "entity_id": "ent_1234567890",
          "created": 1700000000000
        }
      ],
      "meta": {
        "pagination": {
          "order": "desc",
          "has_next": false,
          "limit": 20,
          "has_previous": false,
          "next_cursor": null,
          "previous_cursor": null
        },
        "filters_applied": {}
      }
    }
  }
  ```

  ```json 400-500 lines icon="circle-check" expandable theme={null}
  {
    "status": "error",
    "message": "Failed to retrieve refunds",
    "details": {
      "status": "Invalid status filter value",
      "date_from": "Invalid date format for date_from"
    }
  }
  ```
</CodeGroup>

## Retrieve a Payment Refund by ID

Returns details of a specific payment refund identified by its ULID.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.nuvion.dev/refunds/refund_1234567890 \
    -H "Authorization: Bearer $NUVION_API_KEY" \

  ```
</CodeGroup>

## Request Parameters

<ResponseField name="id" type="string">
  ULID of the payment refund to retrieve
</ResponseField>

<ResponseField name="entity_id" type="string" optional>
  ULID of the entity the payment refund belongs to (optional, used for additional access control)
</ResponseField>

## Response

<CodeGroup>
  ```json 200 OK lines icon="circle-check" expandable theme={null}
  {
      "status": "success",
      "message": "Refund retrieved successfully",
      "data": {
          "id": "refund_1234567890",
          "reference": "refund_001",
          "payment_intent_action_id": "pay_1234567890",
          "amount": 5000,
          "currency": "USD",
          "refund_reason": "Customer requested a refund",
          "status": "pending",
          "status_reason": null,
          "account_id": "acc_1234567890",
          "entity_id": "ent_1234567890",
          "created": 1700000000000
      }   
  }
  ```

  ```json 400-500 lines icon="circle-check" expandable theme={null}
  {
      "status": "error",
      "message": "Failed to retrieve refund",
      "details": {
          "id": "Refund not found with the provided ID",
          "entity_id": "Entity ID does not match the refund's entity"
      }
  }
  ```
</CodeGroup>

## Payment Refund Webhook Events

Payment refund events are sent to your registered webhook endpoint when a refund is completed, or fails. You can listen for the following events:

| Event                      | Types                                   |
| -------------------------- | --------------------------------------- |
| `payment_refund.completed` | A refund request completes successfully |
| `payment_refund.failed`    | A refund request fails                  |

### Payment Refund Event Payloads

<CodeGroup>
  ```json payment_refund_completed lines icon="circle-check" expandable theme={null}
  {
    "event": "payment_refund.completed",
    "data": {
      "id": "01KV814KD8CXG2ANFVX9XSPXXX",
      "reference": "refund_003",
      "payment_intent_action_id": "01KV80YE1HCD5DXP15XBHBAXXX",
      "amount": 5000,
      "currency": "USD",
      "refund_reason": "Customer requested",
      "status": "successful",
      "account_id": "01K8TN588BZKJHZ3VHR2BF3XXX",
      "entity_id": "01K8QZHTWHNGS2Y21HXB36VXXX",
      "created": 1781607321000
    }
  }
  ```

  ```json payment_refund_failed lines icon="circle-check" expandable theme={null}
  {
    "event": "payment_refund.failed",
    "data": {
      "id": "01KV814KD8CXG2ANFVX9XSPXXX",
      "reference": "refund_003",
      "payment_intent_action_id": "01KV80YE1HCD5DXP15XBHBAXXX",
      "amount": 5000,
      "currency": "USD",
      "refund_reason": "Customer requested",
      "status": "failed",
      "status_reason": "Insufficient funds in the account",
      "account_id": "01K8TN588BZKJHZ3VHR2BF3XXX",
      "entity_id": "01K8QZHTWHNGS2Y21HXB36VXXX",
      "created": 1781607321000
    }
  }
  ```
</CodeGroup>