# Refund a payment

`POST https://app.shuttleglobal.com/c/api/instances/{instance_key}/payments/{payment_id}/refund`

You can refund a payment in part or full, or simply mark a payment as refunded (if refunded offline). 
You can refund "PAYMENT" and "CAPTURE" type transactions, but not "AUTH" (void an AUTH to release what is still reserved on it).

Note, support for multi-refund (e.g., I pay $100 and refund $20 followed by a second refund of $80) 
is not available on all gateways.

## Authentication

- basicAuth: Basic Authentication using secret key
- bearerAuth: OAuth 2.0 Bearer Token Authentication

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `payment_id` | path | string | yes | The payment's ID (`pay_...`), capture ID (`ca_...`) or transaction ID (`tr_...`), or the `alt_key` you gave it (case-insensitive). The record must be a payment or capture, otherwise 404 `Payment not found`. An `alt_key` resolves to the newest payment or capture with that key, ignoring failed attempts; if another one with the same `alt_key` was created in the last six months, the request fails with `Duplicate alt_key`. |

## Request body (`application/json`), required

- `refund` (object)
  - `amount` (string): (Optional) The amount of the refund as a string e.g., "10". The amount should not have commas and use a `.` as a decimal separator. If omitted, the entire unrefunded amount of the transaction will be refunded.
  - `reason` (string, required): The reason for the refund (free text)
  - `manual` (boolean): (Optional) Set to true if you do not want to process the refund via the gateway, but simply record that a refund was performed offline.

## Responses

### 200: Refund processed

```json
{
  "refund": {
    "id": "ref_11842_11073",
    "payment": "pay_11842_11072",
    "amount": "10",
    "created": "2020-11-27T15:17:15.000Z",
    "processed": "2020-11-27T15:17:18.000Z",
    "reason": "Customer requested cancellation",
    "reference": "BOLT-00011073",
    "source_transaction": "tr_11842_11072",
    "status": "SUCCESS",
    "gateway_status": "APPROVED",
    "gateway_message": "string",
    "manual": false,
    "currency": "USD",
    "account": "string",
    "parts": [
      {}
    ],
    "offline": false,
    "updated": "2026-01-01T12:00:00Z",
    "v": 0
  }
}
```

### 400: Bad request - invalid parameters

```json
{
  "code": "string",
  "message": "string"
}
```

### 401: Unauthorized - invalid credentials

```json
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}
```

### 404: Payment not found

```json
{
  "code": "string",
  "message": "string"
}
```

## Example request

```sh
curl --request POST \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payments/PAYMENT_ID/refund \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{
  "refund": {
    "amount": "10.00",
    "reason": "Customer returned item",
    "manual": false
  }
}'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/operations/refundpayment/