---
title: "Create a refund"
method: POST
path: "/refunds"
tags: ["Refund"]
---

# Create a refund

`POST /refunds`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/refunds`
- Auth: HTTP bearer

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.


<p class="restricted-notice"><strong>Restricted</strong>: This endpoint is disabled by default. To enable it, you will need to enable refunds on your GoCardless Dashboard.</p>

<p class="notice--warning"><strong>Warning</strong>: A payment that has been (partially) refunded can still receive a late failure or chargeback from the customer's bank.<br /><br />
A refund can only be created once it is outside the safer refund period (7 calendar days after the charge date) otherwise an error is returned. The safer refund period can be disabled by contacting GoCardless.</p>

## Headers

- `GoCardless-Version` string, required

## Request body

- object
  - `refunds` object
    - `amount` union, required: Amount in minor unit (e.g. pence in GBP, cents in EUR).
      - string
      - integer
    - `reference` string, nullable: 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` union: 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>
      - string
      - integer
    - `metadata` CustomerMetadata: 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, required
      - `payment` string: ID of the [payment](https://docs.gocardless.com/docs/api-reference/payment) against which the refund is being made.
      - `mandate` string: ID of the [mandate](https://docs.gocardless.com/docs/api-reference/mandate) against which the refund is being made. <br /> <p class="restricted-notice"><strong>Restricted</strong>: You must request access to Mandate Refunds by contacting <a href="mailto:support@gocardless.com">our support team</a>.</p>

## Response `201`

Resource created successfully

- RefundSingleResourceResponse
  - `refunds` Refund: Refund objects represent (partial) refunds of a [payment](https://docs.gocardless.com/docs/api-reference/payment) back to the [customer](https://docs.gocardless.com/docs/api-reference/customer). GoCardless will notify you via a [webhook](https://docs.gocardless.com/docs/api-reference/webhooks) whenever a refund is created, and will update the `amount_refunded` property of the payment.
    - `id` string, required: Unique identifier, beginning with "RF".
    - `created_at` string, date-time, required: Fixed [timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this resource was created.
    - `amount` integer, required: Amount in minor unit (e.g. pence in GBP, cents in EUR).
    - `currency` string, required: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. This is set to the currency of the refund's [payment](https://docs.gocardless.com/docs/api-reference/payment).
    - `status` 'created' | 'pending_submission' | 'submitted' | 'paid' | 'cancelled' | 'bounced' | 'funds_returned', required: One of: - `created`: the refund has been created - `pending_submission`: the refund has been created, but not yet submitted to the banks - `submitted`: the refund has been submitted to the banks - `paid`: the refund has been included in a [payout](https://docs.gocardless.com/docs/api-reference/payout) - `cancelled`: the refund has been cancelled - `bounced`: the refund has failed to be paid - `funds_returned`: the refund has had its funds returned
    - `reference` string, nullable, required: 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>
    - `metadata` CustomerMetadata, required: 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` RefundLinks, required
      - `payment` string: ID of the [payment](https://docs.gocardless.com/docs/api-reference/payment) against which the refund is being made.
      - `mandate` string: ID of the [mandate](https://docs.gocardless.com/docs/api-reference/mandate) against which the refund is being made.
    - `fx` RefundFx, required
      - `exchange_rate` string, nullable: Rate used in the foreign exchange of the `amount` into the `fx_currency`. Present only after a resource is paid out. Has up to 10 decimal places.
      - `estimated_exchange_rate` string, nullable: Estimated rate that will be used in the foreign exchange of the `amount` into the `fx_currency`. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.
      - `fx_amount` union: Amount that was paid out in the `fx_currency` after foreign exchange. Present only after the resource has been paid out.
        - string, nullable
        - integer
      - `fx_currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD', nullable: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.

## Other responses

- `400`: Bad Request
- `401`: Unauthorised
- `404`: Not found
- `422`: Validation Error
- `500`: Internal Error

---

[API](https://skmtc.dev/gocardless/apis/gocardless-api.md) - [All operations](https://skmtc.dev/gocardless/apis/gocardless-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gocardless/apis/gocardless-api/revisions/4dd3dae45364?raw)