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

# Refund

To return funds to your shopper, refund the payment.

You can refund either the full captured amount or a part of the captured amount. You can also perform multiple partial refunds, as long as their sum doesn't exceed the captured amount.

Some payment methods do not support partial refunds. To learn if a payment method supports partial refunds, refer to the payment method page such as cards, iDEAL, or Klarna.

<Info>You can only refund a payment after it has already been captured.</Info>

## Refund a payment

In order to refund a payment, you will need the transaction id from the transaction you want to refund. You can retrieve this identifier in several ways:

* In a server-to-server integration, the `transactionId` field is returned at the root of the create payment response.
* For a Checkout integration, query the order by its `orderId`. The associated transactions are listed under the `Transactions` node, which includes the `transactionId` field.
* If you have notifications configured, Paybyrd sends a notification for each processed payment. Every notification includes the `transactionId` for that event.
* You can also find the `transactionId` in the Paybyrd dashboard for every transaction in the Transacion Detail view.

## API Call

You can find below an example of how to refund a transaction and the generated response:

```bash theme={null}
curl --request POST \
 --url https://gateway.paybyrd.com/api/v2/refund/4faa13cd-f6ff-414e-b5bd-b61d1e72e418 \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'x-api-key: {your_api_key}' \
 --data '{"amount":"10.00"}'
```

```json theme={null}
{
 "sourceTransaction": {
   "refundedAmount": "10.00",
   "remainingAmount": "0.00",
   "transactionId": "4faa13cd-f6ff-414e-b5bd-b61d1e72e418",
   "amount": "10.00"
 },
 "code": "BYRD200",
 "description": "Operation successfully completed",
 "transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
 "amount": "10.00"
}
```

## Handling rejections

Refunds can be declined, and you must handle these cases in your integration. When a refund cannot be processed, Paybyrd responds with code `BYRD205`. For example:

```bash theme={null}
curl --request POST \
 --url https://gateway.paybyrd.com/api/v2/refund/4faa13cd-f6ff-414e-b5bd-b61d1e72e418 \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'x-api-key: {your_api_key}' \
 --data '{"amount":"5.00"}'
```

```json theme={null}
{
 "sourceTransaction": {
   "refundedAmount": "0.00",
   "remainingAmount": "5.00",
   "transactionId": "4faa13cd-f6ff-414e-b5bd-b61d1e72e418",
   "amount": "5.00"
 },
 "code": "BYRD205",
 "description": "Operation rejected",
 "transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
 "amount": "5.00"
}
```

When you receive `BYRD205`, the refund was declined by the bank. Declines can be temporary, so you can retry the request later. For more information about a declined refund, contact support.

## Handling errors

When the Paybyrd API encounters an error, you receive this response structure:

```json Payment already refunded theme={null}
{
	"isError": true,
	"code": "BYRD230",
	"description": "The refund amount exceeds the remaining balance of the original payment"
}
```

```json Generic error theme={null}
{
	"isError": true,
	"code": "BYRD999",
	"description": "Operation failed. This code is related to unhandled errors."
}
```

You can find the full list of response codes and their descriptions in the [Response code reference](/api-reference/api-code-reference).