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

# Processing Refunds

> Learn when and how to issue refunds, including full and partial refunds. Understand refund scenarios, timing, and how to handle returns in your application.

## What is a Refund?

A **refund** returns money to a customer for a previous payment. This is different from canceling a payment before it's processed—refunds are for payments that have already been completed.

**Common scenarios:**

* Customer returns a product
* Service was not delivered as promised
* Customer cancels and is eligible for a refund
* Partial refund for damaged items or partial service
* Customer dispute resolution

## Why Partial Refunds Exist

Sometimes you need to refund only part of a payment:

**Real-world examples:**

* **Multi-item order**: Customer returns 2 out of 5 items → Partial refund for those 2 items
* **Service cancellation**: Customer cancels mid-month → Refund for unused portion
* **Damaged goods**: Product arrived damaged but customer keeps it → Partial refund as compensation
* **Shipping issues**: Order delayed, customer gets partial refund for inconvenience
* **Subscription proration**: Customer cancels subscription, refund unused portion of current period

**Benefits of partial refunds:**

* Better customer experience (fair refunds)
* Flexibility in handling edge cases
* Can issue multiple partial refunds (as long as total doesn't exceed original amount)

## Refund Basics

### What You Can Refund

* **Any amount up to the original payment** (excluding taxes, see below)
* **Multiple partial refunds** (as long as the total doesn't exceed the original)
* **Full refund** (returns the entire amount)
* **Cannot refund more than the original payment**
* **Cannot refund if already fully refunded**

### Important Limitations

> **Note**: Currently, Revolv3 supports refunds only for transactions processed by Revolv3. If a payment was processed by another payment service provider (PSP), you'll need to handle the refund through that provider.

## How Refunds Work

Here's the process:

1. **You issue a refund** via API or portal
2. **Revolv3 processes the refund** through the same processor that handled the original payment
3. **Money is returned** to the customer's original payment method
4. **Timing varies**:
   * **Credit cards**: Usually 3-10 business days to appear on customer's statement
   * **ACH**: 1-5 business days (similar to ACH payments)

The customer sees the refund on their credit card statement or bank account, but it's not instant—it takes a few days to process.

### Refund Flow Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Revolv3 as Revolv3 API
  participant Processor as Payment processor
  participant Bank as Issuing bank

  App->>Revolv3: POST /invoices/{invoiceId}/refund (amount optional)
  Revolv3->>Revolv3: Validate invoice, amount
  Revolv3->>Processor: Refund request (same processor as original)
  Processor->>Bank: Credit customer
  Bank-->>Processor: Accepted
  Processor-->>Revolv3: Refund result
  Revolv3-->>App: 200 + refund details
```

## Processing a Refund via API

### API Endpoint

```
POST {{Api Root}}/api/Invoices/{invoiceId}/refund
```

Replace `{invoiceId}` with the invoice ID from the original payment.

### Required Parameters

* **`invoiceId`** (in URL): The invoice ID of the original payment transaction. You get this from the payment response when you first charged the customer.
* **`amount`** (in request body, optional): The refund amount.
  * If not provided, defaults to full refund
  * Must be less than or equal to the original amount (excluding taxes)

### Sample Refund Request

**Full refund** (return entire amount):

<CodeGroup>
  ```bash bash theme={null}
  POST /api/Invoices/237058/refund
  {
    // No amount specified = full refund
  }
  ```
</CodeGroup>

**Partial refund** (return specific amount):

<CodeGroup>
  ```bash bash theme={null}
  POST /api/Invoices/237058/refund
  {
    "amount": 1.03 // Refund $1.03 (must be ≤ original amount)
  }
  ```
</CodeGroup>

### Understanding the Request

| **Parameter** | **Description**                                                                              |
| ------------- | -------------------------------------------------------------------------------------------- |
| `invoiceId`   | The invoice ID from the original payment. This links the refund to the original transaction. |
| `amount`      | Optional. Refund amount (excluding taxes). If omitted, refunds the full amount.              |

> **Important**: The refund amount is specified **excluding taxes**. If the original payment included tax, Revolv3 will automatically calculate and refund the proportional tax amount. See the Taxes section below for details.

## Refund Response

When you issue a refund, Revolv3 creates a new invoice for the refund and returns details:

<CodeGroup>
  ```bash bash theme={null}
  {
    "invoice": {
      "invoiceId": 237059, // New invoice ID for this refund
      "parentInvoiceId": 237058, // Links back to original payment
      "customerId": null,
      "merchantInvoiceRefId": null,
      "paymentMethod": {
        "paymentMethodId": 6469,
        "billingAddressId": 7551,
        "billingFirstName": "Joe",
        "billingLastName": "Smith",
        "billingAddress": {
          "addressId": 7551,
          "addressLine1": "381 Forest Ave. Suite C",
          "city": "Laguna Beach",
          "state": "CA",
          "postalCode": "92651",
          "country": "US"
        },
        "paymentMethodCreditCardDetails": {
          "binNumber": "444433",
          "paymentLast4Digit": "1111",
          "paymentExpirationDate": "0330"
        }
      },
      "invoiceStatus": "Refund", // Status indicates this is a refund
      "subtotal": 1.03,
      "tax": 0.0,
      "total": 1.03,
      "billingDate": "7/11/2024"
    },
    "refunds": [
      {
        "invoiceAttemptId": 114130,
        "amount": -1.03, // Negative amount indicates refund
        "invoiceAttemptStatus": "Success",
        "invoiceAttemptDate": "2024-07-11T18:19:28.6971789Z",
        "paymentProcessor": "WorldPay",
        "processorTransactionId": "84082561857760470",
        "responseCode": "000",
        "responseMessage": "Approved"
      }
    ],
    "refundedSubtotal": 1.03, // Total refunded so far (subtotal)
    "refundedTax": 0.0000, // Total tax refunded
    "refundedTotal": 1.03 // Total refunded (subtotal + tax)
  }
  ```
</CodeGroup>

### Understanding the Response

| **Field**                        | **Description**                                                               |
| -------------------------------- | ----------------------------------------------------------------------------- |
| `invoice.invoiceId`              | New invoice ID created for this refund. Save this for your records.           |
| `invoice.parentInvoiceId`        | Links back to the original payment invoice.                                   |
| `invoice.invoiceStatus`          | Will be `"Refund"` for full refunds or `"PartialRefund"` for partial refunds. |
| `refunds[].invoiceAttemptStatus` | Status of the refund attempt. `"Success"` means it was processed.             |
| `refunds[].amount`               | Negative amount (indicates money going back to customer).                     |
| `refundedSubtotal`               | Total amount refunded so far (excluding tax).                                 |
| `refundedTax`                    | Total tax refunded so far.                                                    |
| `refundedTotal`                  | Total refunded (subtotal + tax).                                              |

## Understanding Taxes in Refunds

Tax handling can be confusing. Here's how it works:

### If Original Payment Had No Tax

If the original payment didn't include tax:

* Refund the amount you specify (or full amount if not specified)
* No tax calculation needed

### If Original Payment Included Tax

If the original payment included tax (e.g., from a subscription):

**For full refunds:**

* Specify the refund amount excluding taxes
* Revolv3 automatically refunds the full tax amount as well
* Customer gets back: refund amount + full tax

**For partial refunds:**

* Specify the refund amount excluding taxes
* Revolv3 automatically calculates proportional tax
* Example: If original was \$100 + \$10 tax = \$110 total, and you refund \$50:
  * Customer gets: \$50 (subtotal) + \$5 (proportional tax) = \$55 total

**If you don't specify an amount:**

* Defaults to full refund (including all taxes)

### Example: Tax Refund Calculation

**Original payment:**

* Subtotal: \$100.00
* Tax: \$10.00
* Total: \$110.00

**Partial refund of \$50:**

```bash theme={null}
POST /api/Invoices/12345/refund
{
  "amount": 50.00 // Excluding tax
}
```

**Result:**

* Refunded subtotal: \$50.00
* Refunded tax: \$5.00 (proportional: 50% of original tax)
* Total refunded: \$55.00

## Processing Refunds via Portal

You can also issue refunds through the Revolv3 portal:

1. Go to the **Invoices** screen
2. Select the invoice you want to refund
3. Click **Refund** in the Invoice section
4. Choose:
   * **Full refund**: Return the entire amount
   * **Partial refund**: Enter a specific amount
5. Click **Refund** to process

The portal shows the original transaction amount (excluding taxes) and lets you enter a different amount for partial refunds.

## Real-World Refund Scenarios

### Scenario 1: Customer Returns One Item from Multi-Item Order

**Original order:**

* Item A: \$30.00
* Item B: \$20.00
* Item C: \$15.00
* Total: \$65.00

**Customer returns Item B:**

```bash theme={null}
POST /api/Invoices/12345/refund
{
  "amount": 20.00 // Refund for Item B
}
```

**Result**: Customer gets \$20.00 back. Order status: Partial refund. You can refund more later if needed.

### Scenario 2: Subscription Cancellation with Proration

**Original subscription:**

* Monthly fee: \$29.99
* Customer paid on the 1st
* Customer cancels on the 15th (halfway through month)

**Refund calculation:**

* Unused portion: \$29.99 / 2 = \$14.99

```bash theme={null}
POST /api/Invoices/12345/refund
{
  "amount": 14.99 // Prorated refund
}
```

**Result**: Customer gets \$14.99 back for the unused portion.

### Scenario 3: Multiple Partial Refunds

**Original order:** \$100.00

**First refund:** \$30.00 (customer returns one item)

```bash theme={null}
POST /api/Invoices/12345/refund
{ "amount": 30.00 }
```

**Second refund:** \$20.00 (compensation for delay)

```bash theme={null}
POST /api/Invoices/12345/refund
{ "amount": 20.00 }
```

**Total refunded:** \$50.00 **Remaining:** \$50.00 (can still refund up to this amount)

### Scenario 4: Full Refund

**Customer wants to return entire order:**

```bash theme={null}
POST /api/Invoices/12345/refund
// No amount = full refund
```

**Result**: Customer gets the full amount back. Invoice status: `Refund`.

## Why Refunds Fail

Refunds can fail validation for several reasons:

| **Reason**                       | **Explanation**                                                        |
| -------------------------------- | ---------------------------------------------------------------------- |
| **Amount too high**              | Requested refund exceeds the original payment amount (excluding taxes) |
| **Already fully refunded**       | The invoice has already been fully refunded, no remaining amount       |
| **Partial refunds exceed total** | Sum of all partial refunds would exceed the original amount            |
| **Invoice not found**            | The invoice ID doesn't exist or wasn't processed by Revolv3            |

**What to do if refund fails:**

* Check the error message for the specific reason
* Verify the invoice ID is correct
* Check how much has already been refunded
* Ensure the amount is valid

## Refund Timing Considerations

### Credit Card Refunds

* **Processing time**: Usually processed within 1-2 business days
* **Customer sees it**: 3-10 business days on their statement (depends on their bank)
* **Best practice**: Tell customers it takes 5-10 business days to appear

### ACH Refunds

* **Processing time**: 1-5 business days (similar to ACH payments)
* **Customer sees it**: When the ACH batch processes
* **Best practice**: Tell customers it takes 3-5 business days

### Important Notes

* **Refunds are not instant**: Even though Revolv3 processes them quickly, banks take time to post them
* **Set customer expectations**: Always tell customers when to expect the refund
* **Track refund status**: Use webhooks or API polling to know when refunds complete
* **Keep records**: Store refund invoice IDs for customer support and reconciliation

## Best Practices

1. **Store original invoice IDs**: You'll need them to issue refunds
2. **Set customer expectations**: Tell them refunds take 5-10 business days
3. **Handle partial refunds gracefully**: Have a clear policy on when partial refunds are appropriate
4. **Track refund history**: Keep records of all refunds for customer support
5. **Use webhooks**: Get notified when refunds complete
6. **Reconcile regularly**: Match refunds with your accounting records
7. **Have a refund policy**: Clear policy helps avoid disputes

## Common Questions

**Q: Can I refund more than the original payment?** A: No, you can only refund up to the original payment amount (excluding taxes).

**Q: How long do refunds take?** A: Revolv3 processes them quickly (1-2 days), but banks take 3-10 business days to show them on customer statements.

**Q: Can I cancel a refund?** A: No, once a refund is issued, it cannot be cancelled. You'd need to charge the customer again if you made a mistake.

**Q: What if the customer's card is expired?** A: The refund will still go through—banks handle expired card refunds automatically.

**Q: Can I refund to a different payment method?** A: No, refunds always go back to the original payment method. If the customer wants a different method, you'd need to process it as a new transaction.

## Next Steps

* [**Invoice Status**](/docs/core-concepts/invoice/invoice-status) — Understand refund statuses (`Refund`, `PartialRefund`)
* [**Subscriptions**](/docs/core-concepts/subscription/canceling-a-subscription) — Learn about canceling subscriptions and refunds
* [**Webhooks**](/docs/webhook-events/webhook) — Set up notifications for refund completions

***