> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Referenced refunds

Return money to a customer's original payment method by refunding the payment behind a credited invoice through your Payment Service Provider (PSP).

---

## Why this matters

A credit note corrects the accounting, but if the customer already paid the original invoice, the money is still with you. A referenced refund closes that gap: it instructs the PSP to refund the original payment transaction, so the funds flow back to the payment method the customer paid with and the refund reconciles against the original payment in both your PSP and accounting systems.

A *referenced* refund is a refund of a specific earlier payment, tied to that payment's transaction at the PSP. This is different from an *un-referenced* refund, which is a standalone payout to the customer that isn't linked to any previous payment.

## How it works

The refund action is called on the **credit note**, not on the original invoice. Solvimon looks up the payment of the original invoice (the invoice the credit note was created from) and submits a refund request for that payment to the PSP.

```mermaid
sequenceDiagram
    participant You
    participant Solvimon
    participant PSP
    You->>Solvimon: POST /v1/invoices/{credit_note_id}/refund
    Solvimon->>Solvimon: Look up payment on the original invoice
    Solvimon->>PSP: Submit referenced refund for that payment
    PSP-->>You: Funds returned to the customer's payment method
```

The refund only works on invoices that meet all of the following conditions:

| Condition                                                  | Why                                                                                                                                         |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Type is `CREDIT`                                           | The refund is triggered from the credit note, which defines the amount to return.                                                           |
| Status is `FINAL`                                          | Draft credit notes can still change; only finalized ones can be refunded.                                                                   |
| Not already paid                                           | A refunded credit note is settled, so this guards against refunding twice.                                                                  |
| The original invoice has at least one `AUTHORIZED` payment | There must be a PSP payment to reference. An invoice settled outside a PSP (for example by bank transfer) has no payment to refund against. |

If any condition isn't met, the refund action is rejected.

## Refunding a credit note

### Via API

First [credit the invoice](/platform-guides/invoicing/invoice-corrections/credit-invoices) and finalize the credit note. Then call [POST /v1/invoices/\{id}/refund](https://docs.solvimon.com/api-docs/transaction-api/invoices/post-invoices-by-resource-id-refund) on the credit note. The request has no body:

### Request

POST [https://test.api.solvimon.com/v\{version}/invoices/\{resourceId}/refund](https://test.api.solvimon.com/v\{version}/invoices/\{resourceId}/refund)

```curl
curl -X POST https://test.api.solvimon.com/v1/invoices//refund \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

```python
import requests

url = "https://test.api.solvimon.com/v1/invoices/:resourceId/refund"

payload = {}
headers = {
    "X-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://test.api.solvimon.com/v1/invoices/:resourceId/refund';
const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://test.api.solvimon.com/v1/invoices/:resourceId/refund"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://test.api.solvimon.com/v1/invoices/:resourceId/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://test.api.solvimon.com/v1/invoices/:resourceId/refund")
  .header("X-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://test.api.solvimon.com/v1/invoices/:resourceId/refund', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://test.api.solvimon.com/v1/invoices/:resourceId/refund");
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://test.api.solvimon.com/v1/invoices/:resourceId/refund")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

The response is the credit note, linked to the original invoice whose payment is being refunded:

### Response (200)

```json
{
  "object_type": "invoice",
  "id": "inv_1234567890abcdef",
  "invoice_number": "INV-2024-0001",
  "purchase_order_number": "PO-987654321",
  "platform_id": "platform_001",
  "sales_tax_percentage": "5.00",
  "customer": {
    "object_type": "customer",
    "id": "cust_001",
    "created_at": "2024-01-10T08:00:00Z",
    "parent_customer_id": "cust_parent_001",
    "parent_customer_ids": [
      "cust_parent_001",
      "cust_grandparent_001"
    ],
    "reference": "CUST-REF-001",
    "status": "DRAFT",
    "timezone": "Asia/Dubai",
    "type": "ORGANIZATION",
    "email": "contact@customerexample.com",
    "notification_preferences": [
      {
        "type": "INVOICE",
        "channels": [
          {
            "type": "EMAIL",
            "enabled": true
          }
        ]
      }
    ],
    "locale": "en_AE",
    "individual": {
      "name": {
        "first_name": "John",
        "last_name": "Doe",
        "infix": ""
      },
      "residential_address": {
        "line1": "123 Palm Street",
        "line2": "Suite 4B",
        "city": "Dubai",
        "postal_code": "00000",
        "state": "Dubai",
        "country": "AE"
      }
    },
    "organization": {
      "legal_name": "Customer Example LLC",
      "tax_id": "AE123456789",
      "tax_ids": [
        {
          "id": "AE123456789",
          "type": "VAT"
        }
      ],
      "registration_number": "REG-987654321",
      "tax_exempt": false,
      "tax_exempt_note": "",
      "registered_address": {
        "line1": "123 Palm Street",
        "line2": "Suite 4B",
        "city": "Dubai",
        "postal_code": "00000",
        "state": "Dubai",
        "country": "AE"
      }
    },
    "custom_fields": [
      {
        "id": "cf_001",
        "reference": "customer_custom_field_1",
        "value": "Preferred Customer",
        "values": [
          "Preferred Customer"
        ],
        "integration_details": {
          "id": "int_001",
          "reference": "int_ref_001",
          "payment_gateway_variant": "ADYEN",
          "adyen": {
            "recurring_detail_reference": "recurring_123"
          },
          "stripe": {
            "payment_method_id": "pm_123456789"
          }
        }
      }
    ],
    "pricing_plan_subscription_selector": {
      "data": [
        {
          "field": "BILLING_ENTITY_REGISTERED_ADDRESS_COUNTRY",
          "value": "AE"
        }
      ],
      "rules": [
        {
          "field": "BILLING_ENTITY_REGISTERED_ADDRESS_COUNTRY",
          "type": "EQUALS"
        }
      ],
      "filters": [
        {
          "field": "BILLING_ENTITY_REGISTERED_ADDRESS_COUNTRY",
          "type": "EQUALS",
          "value": "AE"
        }
      ],
      "fallback": "LATEST"
    },
    "linked_integrations": [
      {
        "id": "link_001",
        "link_details": [
          {
            "url": "https://integration.example.com/customer/cust_001",
            "custom_field_name": "external_customer_id"
          }
        ]
      }
    ],
    "roles": [
      "DEFAULT"
    ],
    "processing_only": false
  },
  "billing_entity": {
    "object_type": "billing_entity",
    "id": "be_001",
    "created_at": "2023-12-01T09:00:00Z",
    "reference": "BE-REF-001",
    "status": "ACTIVE",
    "timezone": "Asia/Dubai",
    "legal_name": "Billing Entity LLC",
    "tax_id": "AE987654321",
    "tax_ids": [
      {
        "id": "AE987654321",
        "type": "VAT"
      }
    ],
    "registration_number": "REG-123456789",
    "registered_address": {
      "line1": "456 Business Bay",
      "line2": "Floor 10",
      "city": "Dubai",
      "postal_code": "00001",
      "state": "Dubai",
      "country": "AE"
    },
    "email": "billing@billingentity.com",
    "tax_settings": {
      "apply_local_vat_for_missing_tax_id": true
    },
    "tax_registrations": [
      {
        "id": "taxreg_001",
        "description": "VAT Registration UAE",
        "tax_id": "AE987654321",
        "tax_ids": [
          {
            "id": "AE987654321",
            "type": "VAT"
          }
        ],
        "registration_number": "REG-123456789",
        "registered_address": {
          "line1": "456 Business Bay",
          "line2": "Floor 10",
          "city": "Dubai",
          "postal_code": "00001",
          "state": "Dubai",
          "country": "AE"
        }
      }
    ],
    "custom_fields": [
      {
        "id": "cf_be_001",
        "reference": "billing_entity_custom_field_1",
        "value": "Priority Billing",
        "values": [
          "Priority Billing"
        ],
        "integration_details": {
          "id": "int_be_001",
          "reference": "int_ref_be_001",
          "payment_gateway_variant": "ADYEN",
          "adyen": {
            "recurring_detail_reference": "recurring_be_123"
          },
          "stripe": {
            "payment_method_id": "pm_be_123456789"
          }
        }
      }
    ],
    "default_customer_country_selector": [
      "AE"
    ],
    "default_billing_currency_selector": [
      "AED"
    ],
    "linked_integrations": [
      {
        "id": "link_be_001",
        "link_details": [
          {
            "url": "https://integration.example.com/billing_entity/be_001",
            "custom_field_name": "external_billing_entity_id"
          }
        ]
      }
    ]
  },
  "status": "PAID",
  "on_hold": false,
  "type": "STANDARD",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-20T10:00:00Z",
  "invoice_date": "2024-01-15T09:30:00Z",
  "delivery_date": "2024-01-16T09:30:00Z",
  "due_date": "2024-02-15T09:30:00Z",
  "billing_period_date": "2024-01-01T00:00:00Z",
  "billing_currency": "AED",
  "invoice_amount_including_tax": {
    "quantity": "1050.00",
    "currency": "AED"
  },
  "open_invoice_amount": {
    "quantity": "0.00",
    "currency": "AED"
  },
  "closed_invoice_amount": {
    "quantity": "1050.00",
    "currency": "AED"
  },
  "timezone": "Asia/Dubai",
  "billing_period": {
    "type": "MONTH",
    "value": 1
  },
  "pricing_plan_subscription_ids": [
    "sub_001"
  ],
  "pricing_amount_type": "EXCLUDING_TAX",
  "periods": [],
  "closed_periods": [],
  "tax_categories": [
    {
      "base_amount": {
        "quantity": "1000.00",
        "currency": "AED"
      },
      "tax_amount": {
        "quantity": "50.00",
        "currency": "AED"
      },
      "total_amount": {
        "quantity": "1050.00",
        "currency": "AED"
      },
      "category": "STANDARD",
      "local_amounts": {
        "base_amount": {
          "quantity": "1000.00",
          "currency": "AED"
        },
        "tax_amount": {
          "quantity": "50.00",
          "currency": "AED"
        },
        "total_amount": {
          "quantity": "1050.00",
          "currency": "AED"
        },
        "used_exchange_rate": {
          "currency": "AED",
          "base_currency": "AED",
          "rate_timestamp": "2024-01-15T00:00:00Z",
          "rate": "1.0",
          "source": "Internal"
        },
        "display": true
      },
      "notes": [
        "Standard VAT rate applied"
      ],
      "rates": [
        {
          "name": "VAT Standard Rate",
          "percentage": "5.00",
          "tax_amount": {
            "quantity": "50.00",
            "currency": "AED"
          }
        }
      ],
      "percentage": "5.00",
      "name": "VAT"
    }
  ],
  "tax_summary": {
    "base_amount": {
      "quantity": "1000.00",
      "currency": "AED"
    },
    "tax_amount": {
      "quantity": "50.00",
      "currency": "AED"
    },
    "total_amount": {
      "quantity": "1050.00",
      "currency": "AED"
    },
    "local_amounts": {
      "base_amount": {
        "quantity": "1000.00",
        "currency": "AED"
      },
      "tax_amount": {
        "quantity": "50.00",
        "currency": "AED"
      },
      "total_amount": {
        "quantity": "1050.00",
        "currency": "AED"
      },
      "used_exchange_rate": {
        "currency": "AED",
        "base_currency": "AED",
        "rate_timestamp": "2024-01-15T00:00:00Z",
        "rate": "1.0",
        "source": "Internal"
      },
      "display": true
    },
    "notes": [
      "Summary of VAT applied"
    ],
    "country_code": "AE"
  },
  "dunning_actions": [],
  "payment_acceptor_ids": [
    "payacc_001"
  ],
  "payment_actions": [],
  "pay_invoice_link": {
    "expiry_period": {
      "type": "DAY",
      "value": 30
    },
    "portal_url_id": "portal_001",
    "url": "https://pay.example.com/invoice/inv_1234567890abcdef"
  },
  "notes": [
    "Invoice paid in full on 2024-01-20"
  ],
  "linked_invoices": [],
  "custom_fields": [],
  "other_custom_fields": [],
  "credit": {
    "original_invoice_info": {
      "id": "inv_0000000000000001",
      "invoice_number": "INV-2023-0999"
    },
    "note": "Refund issued for overpayment",
    "original_invoice_id": "inv_0000000000000001"
  },
  "e_invoices": [],
  "used_exchange_rates": [
    {
      "currency": "AED",
      "base_currency": "AED",
      "rate_timestamp": "2024-01-15T00:00:00Z",
      "rate": "1.0",
      "source": "Internal"
    }
  ],
  "processing_only_customers": [],
  "meter_values": [],
  "credit_types": [],
  "display_invoice_sub_lines_per_processing_only_customer": false,
  "forwarded_from_customers": [],
  "validation_result": [
    {
      "status": "VALID",
      "details": "Invoice data validated successfully"
    }
  ],
  "reprocess": null,
  "used_tax_registration": {
    "id": "taxreg_001",
    "description": "VAT Registration UAE",
    "tax_id": "AE987654321",
    "tax_ids": [
      {
        "id": "AE987654321",
        "type": "VAT"
      }
    ],
    "registration_number": "REG-123456789",
    "registered_address": {
      "line1": "456 Business Bay",
      "line2": "Floor 10",
      "city": "Dubai",
      "postal_code": "00001",
      "state": "Dubai",
      "country": "AE"
    }
  },
  "footnote": "Thank you for your business.",
  "approval_status": "APPROVED",
  "updated_to_final_at": "2024-01-20T10:00:00Z",
  "has_usage_based_pricing": false,
  "coupons": [],
  "promotion_codes": [],
  "linked_integrations": [],
  "paid": true,
  "auto_rescues": [],
  "linked_invoices_ids": [],
  "to_be_reprocessed": false,
  "to_be_reprocessed_at": null
}
```

> **Note**
>
> The refund request is submitted to the PSP asynchronously. The PSP processes it and returns the funds to the customer's original payment method on its own schedule.

### Via Desk

Open the credit note and select the refund action from the invoice menu. The action is only shown when the conditions above are met.

## Edge cases

* **Refunding twice**: once a credit note has been refunded it counts as paid, and further refund attempts are rejected.
* **No PSP payment on the original invoice**: if the original invoice was never paid through a PSP, there is no payment to reference. Settle the credit with the customer outside Solvimon, or refund a specific payment directly with [POST /v1/payments/\{id}/refund](https://docs.solvimon.com/api-docs/transaction-api/payments/post-payments-by-resource-id-refund).

---

See also: [Correcting invoices](/platform-guides/invoicing/invoice-corrections), [Credit notes](/platform-guides/invoicing/invoice-corrections/credit-invoices) and [Invoice lifecycle](/platform-guides/invoicing/invoices/invoice-lifecycle).