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

# Refund a Payment Transaction

> Check what can be refunded, create the refund, move the money and follow it

You choose whether a refund moves money straight away or is held until you execute it. Refunds send no webhook events, so follow them by polling.

| # | Step | Who |
| - | - | - |
| 1 | Read the refundable amount | API |
| 2 | Create the refund, moving or held | API |
| 3 | Execute a held refund | API |
| 4 | Resolve anything blocking it | **Person** in Console, or **Quidkey** |
| 5 | Follow the refund until it's `completed` | API, polling |
| 6 | Read the payment transaction's refund status | API |

## 1. Read the Refundable Amount

```bash theme={null}
curl 'https://api.quidkey.com/v1/transactions/tx_1/refundable-amount' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

```json Response theme={null}
{
  "result": {
    "_type": "refundable_amount",
    "_uri": "/transactions/tx_1/refundable-amount",
    "_view": "full",
    "id": "tx_1",
    "transaction": { "_link": "/transactions/tx_1", "_type": "transaction", "id": "tx_1" },
    "amount": { "value": 2550, "currency": "EUR" },
    "created_at": null,
    "updated_at": null
  },
  "entities": {},
  "not_included": []
}
```

`amount` is the most a new refund may ask for now, in the customer's currency. A payment transaction whose customer hasn't paid yet reads zero.

The payment transaction's `can_refund` says whether a refund that moves money can be created now. A payment transaction that's still `processing` reads `can_refund: false` beside a refundable amount: you can prepare a refund held with `execution: manual`, and executing it waits, with `PAYMENT_IN_TRANSIT`, until the payment transaction converts.

## 2. Create the Refund

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/transactions/tx_1/refunds' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "5d6e7f80-91a2-4b3c-8d4e-5f6a7b8c9d0e"' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": { "value": 1050, "currency": "EUR" },
    "execution": "automatic",
    "reason": "Item returned"
  }'
```

Make one `Idempotency-Key` for each refund you mean to make, and store it with your record of the refund before you send the request. A retry with the same key answers the refund the first attempt made. A retry with a new key is a second refund. See [Idempotency](https://docs.quidkey.com/api-v1/standards/idempotency.md#choosing-a-key).

`execution` is required, with no default:

* `automatic` creates the refund, and Quidkey moves the money as soon as it can, with no further call.
* `manual` creates it and holds it until you call `:executeRefund`. A held refund blocks further refunds of the payment transaction until it's executed, or cancelled by Quidkey support.

The answer is 201, with the refund itself, a `transaction` of `type: refund` whose `parent_transaction` is the payment transaction. Its `Location` header is `/transactions/{refund_id}`.

| Refund `status` | `required_actions` | Meaning |
| - | - | - |
| `processing` | `[]` | The money is moving. |
| `pending` | `REFUND_NOT_EXECUTED` | Held, as you asked. Call `:executeRefund` when it should move. |
| `pending` | Other codes | Nothing has moved. It goes on by itself once they clear. |
| `pending` | `[]` | Nothing has moved, and it's waiting on Quidkey. |
| `processing` | Some codes | Something stopped it on the way, and it goes on once they clear. |

| Refusal | What to do |
| - | - |
| 409 `PAYMENT_BUSY`, or a 503 | Send the same request with the same key. |
| 409 `REFUND_IN_PROGRESS` | A refund of this payment transaction is already under way. |
| 409 `TRANSACTION_NOT_REFUNDABLE` | The customer hasn't paid yet. |
| 422 `REFUND_AMOUNT_EXCEEDED` | Ask for no more than the refundable amount. |
| 422 `REFUND_MANAGED_BY_PLATFORM` | The payment transaction came through a platform such as Shopify, which pays its refunds. `execution: manual` can still prepare one. |

## 3. Execute a Held Refund

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/transactions/tx_2:executeRefund' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

Call it on the refund's ID. It answers 200 with the refund, `processing`, or `pending` with the `required_actions` that hold it. It's safe to repeat: a refund already `processing` or `completed` answers 200. A `failed` or `cancelled` refund answers 409 `REFUND_NOT_PENDING`. While another request is working on the refund, it answers 409 `REFUND_BUSY`, which is `retryable`: send the same request again.

A refund of a payment transaction still in transit waits with `PAYMENT_IN_TRANSIT`, and goes on by itself once the payment transaction converts.

If `:executeRefund` answers 503 `OUTCOME_UNKNOWN`, the refund still goes on. Read it, or call `:executeRefund` again, to see where it stands.

## 4. Resolve What Blocks It

Each entry in `required_actions` says who resolves it, in `actor`:

| `actor` | What happens |
| - | - |
| `api` | Make the call the code names. `REFUND_NOT_EXECUTED` means `:executeRefund`. |
| `person` | Someone supplies the missing details in Console, or sends the customer a resolution link from there. For `REFUND_BALANCE_TOO_LOW`, someone tops up the refund account, and it's retried hourly. **Person.** |
| `quidkey` | There's nothing to do: Quidkey retries it, or its staff handle it. **Quidkey.** |

A held or blocked refund that shouldn't go ahead is cancelled by Quidkey support, and then reads `cancelled`. The API doesn't cancel refunds.

## 5. Follow the Refund

```bash theme={null}
curl 'https://api.quidkey.com/v1/transactions/tx_2' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

Poll until the refund reads `completed`, which means the payment to the customer's account went out. `GET /transactions/{id}/refunds` lists all of a payment transaction's refunds.

## 6. Read the Payment Transaction

```bash theme={null}
curl 'https://api.quidkey.com/v1/transactions/tx_1' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

The payment transaction's `refund_status` reads `partially_refunded` or `fully_refunded`, and `can_refund` reads `true` again while more can be refunded.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.