GoCardlessDeveloper Docs
Create a sandbox account

Refund

View as Markdown

Refund objects represent (partial) refunds of a payment back to the customer.

GoCardless will notify you via a webhook whenever a refund is created, and will update the amount_refunded property of the payment.

Create a refund#

POST/refunds

Creates a new refund object.

This fails with:

  • 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.

POST https://api.gocardless.com/refunds HTTP/1.1
Content-Type: application/json
{
  "refunds": {
    "amount": 100,
    "total_amount_confirmation": 150,
    "reference": "Acme refund",
    "metadata": {
      "reason": "late delivery"
    },
    "links": {
      "payment": "PM123"
    }
  }
}
@client.refunds.create(
  params: {
    amount: 100,
    total_amount_confirmation: 150,
    reference: "Service refund",
    metadata: { reason: "Late delivery" },
    links: { payment: "PM123"}
  }
)
client.refunds.create(params={
  "amount": 100,
  "total_amount_confirmation": 150,
  "reference": "Acme refund",
  "metadata": {
    "reason": "late delivery"
  },
  "links": {
    "payment": "PM123"
  }
})
const refund = await client.refunds.create({
  amount: "100",
  total_amount_confirmation: "150",
  reference: "Acme refund",
  metadata: {
    reason: "late delivery"
  },
  links: {
    payment: "PM123"
  }
});
$client->refunds()->create([
  "params" => ["amount" => 100,
               "total_amount_confirmation" => 150,
               "reference" => "Acme refund",
               "metadata" => ["reason" => "Late delivery"],
               "links" => ["payment" => "PM123"]]
]);
client.refunds().create()
  .withAmount(100)
  .withTotalAmountConfirmation(150)
  .withReference("Acme refund")
  .withMetadata("reason", "late delivery")
  .withLinksPayment("PM123")
  .execute();
refundCreateParams := gocardless.RefundCreateParams{
  Amount:                  100,
  TotalAmountConfirmation: 150,
  Reference:               "Acme refund",
  Metadata:                map[string]string{"reason": "late delivery"},
  Links: gocardless.RefundCreateParamsLinks{
    Payment: "PM123",
  },
}

refund, err := client.Refunds.Create(ctx, refundCreateParams)
var refundRequest = new GoCardless.Services.RefundCreateRequest()
{
    Amount = 100,
    TotalAmountConfirmation = 150,
    Reference = "Partial refund",
    Links = new GoCardless.Services.RefundCreateRequest.RefundLinks()
    {
        Payment = "PM0123"
    }
};
var refundResponse = await client.Refunds.CreateAsync(refundRequest);
GoCardless.Resources.Refund refund = refundResponse.Refund;
Responsehttp
HTTP/1.1 201 Created
Location: /payments/RF123
Content-Type: application/json
{
  "refunds": {
    "id": "RF123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "amount": 100,
    "currency": "GBP",
    "reference": "Acme refund",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "status": "created",
    "metadata": {
      "reason": "late delivery"
    },
    "links": {
      "payment": "PM123"
    }
  }
}

// Or, if the creditor does not have a sufficient balance to create the refund:
HTTP/1.1 422 Validation Failed
Content-Type: application/json
{
  "error": {
    "message": "It’s not possible to process this refund because you don’t have enough funds in GBP. Your available refund amount for payments in GBP is: 0.9 GBP",
    "errors": [
        {
            "reason": "available_refund_amount_insufficient",
            "message": "It’s not possible to process this refund because you don’t have enough funds in GBP. Your available refund amount for payments in GBP is: 0.9 GBP",
            "metadata": {
              "available_refund_amount": 90
            }
        }
    ],
    "documentation_url": "https://developer.gocardless.com/api-reference#available_refund_amount_insufficient",
    "type": "validation_failed",
    "request_id": "...",
    "code": 422
  }
}
Request Body
refundsobject
5 properties
amountobject

Amount in minor unit (e.g. pence in GBP, cents in EUR).

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

total_amount_confirmationobject

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.
Must be supplied if links[payment] is present.

It is possible to opt out of requiring total_amount_confirmation, please contact our support team for more information.

metadataobject

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.

linksobject
2 properties
paymentstring

ID of the payment against which the refund is being made.

mandateobject
Response 201

Resource created successfully

refundsobject
9 properties
idstring

Unique identifier, beginning with "RF".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

Amount in minor unit (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. This is set to the currency of the refund's payment.

statusstring

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
  • cancelled: the refund has been cancelled
  • bounced: the refund has failed to be paid
  • funds_returned: the refund has had its funds returned
createdpending_submissionsubmittedpaidcancelledbouncedfunds_returned
referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

metadataobject

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.

linksobject
2 properties
paymentstring

ID of the payment against which the refund is being made.

mandatestring

ID of the mandate against which the refund is being made.

fxobject
4 properties
exchange_ratestring

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_ratestring

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_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 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.

AUDCADDKKEURGBPNZDSEKUSD
Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

List refunds#

GET/refunds

Returns a cursor-paginated list of your refunds.

GET https://api.gocardless.com/refunds HTTP/1.1
@client.refunds.list

@client.refunds.list(params: { payment: "PM123" })

@client.refunds.list.records.each { |refund| puts refund.inspect }
client.refunds.list().records

client.refunds.list(params={"payment": "PM123"}).records
const refunds = await client.refunds.list();

// List all refunds associated with a given mandate.
const mandateRefunds = await client.refunds.list({ mandate: "MD0123" });
$client->refunds()->list();

$client->refunds()->list([
  "params" => ["payment" => "PM123"]
]);
for (Refund refund : client.refunds().all().withPayment("PM123").execute()) {
  System.out.println(refund.getId());
}
refundListParams := gocardless.RefundListParams{
  Mandate: "MD123",
}
refundListResult, err := client.Refunds.List(ctx, refundListParams)
for _, refund := range refundListResult.Refunds {
    fmt.Println(refund.Id)
}
var refundRequest = new GoCardless.Services.RefundListRequest()
{
    Mandate = "MD0123"
};

var refundListResponse = client.Refunds.All(refundRequest);
foreach (GoCardless.Resources.Refund refund in refundListResponse)
{
    Console.WriteLine(refund.Id);
}
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "refunds": [{
    "id": "RF123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "amount": 100,
    "currency": "GBP",
    "reference": "Acme refund",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "status": "created",
    "metadata": {
      "reason": "late failure"
    },
    "links": {
      "payment": "PM123"
    }
  }]
}
Response 200

Successful response

refundsarray
9 properties
idstring

Unique identifier, beginning with "RF".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

Amount in minor unit (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. This is set to the currency of the refund's payment.

statusstring

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
  • cancelled: the refund has been cancelled
  • bounced: the refund has failed to be paid
  • funds_returned: the refund has had its funds returned
createdpending_submissionsubmittedpaidcancelledbouncedfunds_returned
referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

metadataobject

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.

linksobject
2 properties
paymentstring

ID of the payment against which the refund is being made.

mandatestring

ID of the mandate against which the refund is being made.

fxobject
4 properties
exchange_ratestring

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_ratestring

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_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 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.

AUDCADDKKEURGBPNZDSEKUSD
metaobject
2 properties
limitinteger
cursorsobject
2 properties
beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

Get a single refund#

GET/refunds/{refund_id}

Retrieves all details for a single refund

Path Parameters

NameTypeDescription
refund_idrequiredstring

The refund id

GET https://api.gocardless.com/refunds/RF123 HTTP/1.1
@client.refunds.get("RF123")
client.refunds.get("RF123")
const refund = await client.refunds.find("RF123");
$client->refunds()->get("RF123");
Refund refund = client.refunds().get("RF123").execute();
refund, err := client.Refunds.Get(ctx, "RF123")
var refundResponse = await client.Refunds.GetAsync("RF0123");
GoCardless.Resources.Refund refund = refundResponse.Refund;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "refunds": {
    "id": "RF123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "amount": 100,
    "currency": "GBP",
    "reference": "Acme refund",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "status": "created",
    "metadata": {
      "reason": "late failure"
    },
    "links": {
      "payment": "PM123"
    }
  }
}
Response 200

Successful response

refundsobject
9 properties
idstring

Unique identifier, beginning with "RF".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

Amount in minor unit (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. This is set to the currency of the refund's payment.

statusstring

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
  • cancelled: the refund has been cancelled
  • bounced: the refund has failed to be paid
  • funds_returned: the refund has had its funds returned
createdpending_submissionsubmittedpaidcancelledbouncedfunds_returned
referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

metadataobject

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.

linksobject
2 properties
paymentstring

ID of the payment against which the refund is being made.

mandatestring

ID of the mandate against which the refund is being made.

fxobject
4 properties
exchange_ratestring

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_ratestring

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_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 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.

AUDCADDKKEURGBPNZDSEKUSD
Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

Update a refund#

PUT/refunds/{refund_id}

Updates a refund object.

Path Parameters

NameTypeDescription
refund_idrequiredstring

The refund id

PUT https://api.gocardless.com/refunds/RF123 HTTP/1.1
Content-Type: application/json
{
  "refunds": {
    "metadata": {
      "key": "value"
    }
  }
}
@client.refunds.update(
  "RF123",
  params: {
    metadata: { reason: "Late delivery", internal_code: "refund_1A" }
  }
)
client.refunds.update("RF123", params={
  "metadata": {"key": "value"}
})
const refund = await client.refunds.update(
  "RF123",
  {
    metadata: {
      key: "value"
    }
  }
);
$client->refunds()->update("RF123", [
  "params" => ["metadata" => ["key" => "value"]]
]);
client.refunds().update("RF123")
  .withMetadata("internal_code", "refund_1A")
  .execute();
refundUpdateParams := gocardless.RefundUpdateParams{
  Metadata: map[string]string{"key": "value"},
}
refund, err := client.Refunds.Update(ctx, "RF123", refundUpdateParams)
var refundRequest = new GoCardless.Services.RefundUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"reason", "Late delivery"}
    }
};

var refundResponse = await client.Refunds.UpdateAsync("RF0123", refundRequest);
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "refunds": {
    "id": "RF123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "amount": 100,
    "currency": "GBP",
    "reference": "Acme refund",
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "status": "created",
    "metadata": {
      "key": "value"
    },
    "links": {
      "payment": "PM123"
    }
  }
}
Request Body
refundsobject
1 properties
metadataobject

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.

Response 200

Successful response

refundsobject
9 properties
idstring

Unique identifier, beginning with "RF".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

Amount in minor unit (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. This is set to the currency of the refund's payment.

statusstring

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
  • cancelled: the refund has been cancelled
  • bounced: the refund has failed to be paid
  • funds_returned: the refund has had its funds returned
createdpending_submissionsubmittedpaidcancelledbouncedfunds_returned
referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

metadataobject

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.

linksobject
2 properties
paymentstring

ID of the payment against which the refund is being made.

mandatestring

ID of the mandate against which the refund is being made.

fxobject
4 properties
exchange_ratestring

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_ratestring

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_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 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.

AUDCADDKKEURGBPNZDSEKUSD
Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject
SupportDashboard