# Refund

Source: https://docs.gocardless.com/docs/api-reference/refund

## Create a refund

`POST /refunds`

Creates a new refund object.

This fails with:<a name="total_amount_confirmation_invalid"></a><a name="number_of_refunds_exceeded"></a><a name="available_refund_amount_insufficient"></a>

- `total_amount_confirmation_invalid` if the confirmation amount doesn't match the total amount refunded for the payment. This safeguard is there to prevent two processes from creating refunds without awareness of each other.

- `available_refund_amount_insufficient` if the creditor does not have sufficient balance for refunds available to cover the cost of the requested refund.

### Request body

Wrap request body attributes in a `refunds` object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | string / integer | No | Amount in minor unit (e.g. pence in GBP, cents in EUR). |
| `reference` | string | No | An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.<br /> <strong>ACH</strong> - 10 characters<br /> <strong>Autogiro</strong> - 11 characters<br /> <strong>Bacs</strong> - 10 characters<br /> <strong>BECS</strong> - 30 characters<br /> <strong>BECS NZ</strong> - 12 characters<br /> <strong>Betalingsservice</strong> - 30 characters<br /> <strong>Faster Payments</strong> - 18 characters<br /> <strong>PAD</strong> - scheme doesn't offer references<br /> <strong>PayTo</strong> - 18 characters<br /> <strong>SEPA</strong> - 140 characters<br /> Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. <p class='restricted-notice'><strong>Restricted</strong>: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the <a href='https://gocardless.com/pricing'>GoCardless Plus, Pro or Enterprise packages</a>.</p> <p class='restricted-notice'><strong>Restricted</strong>: You can not specify a payment reference for Faster Payments.</p> |
| `total_amount_confirmation` | string / integer | No | Total expected refunded amount in minor unit (e.g. pence/cents/öre). If there are other partial refunds against this payment, this value should be the sum of the existing refunds plus the amount of the refund being created. <br /> Must be supplied if `links[payment]` is present. <p class="notice">It is possible to opt out of requiring <code>total_amount_confirmation</code>, please contact <a href="mailto:support@gocardless.com">our support team</a> for more information.</p> |
| `metadata` | object | No | Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. |
| `links` | object | No |  |

### Responses

| Status | Description |
| --- | --- |
| 201 | Resource created successfully |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## List refunds

`GET /refunds`

Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your refunds.

### Responses

| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## Get a single refund

`GET /refunds/{refund_id}`

Retrieves all details for a single refund

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `refund_id` | path | string | Yes | The refund id |

### Responses

| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## Update a refund

`PUT /refunds/{refund_id}`

Updates a refund object.

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `refund_id` | path | string | Yes | The refund id |

### Request body

Wrap request body attributes in a `refunds` object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metadata` | object | No | Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. |

### Responses

| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |