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

# Refunds

> Full and partial refunds, and how the service fee is handled.

Refund requests identify a payment by its `id`. A payment's **line items** describe what was paid for (each with its share of the service fee); they are not refunded individually.

<Note>
  **Line-item refunds are not supported.** Pass the payment's `id` in the `{id}` path parameter; a line-item `id` returns `404 PAYMENT_NOT_FOUND`.
</Note>

## Full and partial refunds

The principal is the payment amount excluding the service fee.

| Request body | What is refunded |
| - | - |
| `{}` (no `amountCents`) | All of the remaining **principal** |
| `{ "amountCents": 2500 }` | 2500 cents of principal |
| `{ "feeType": "include_fee" }` (no `amountCents`) | All remaining principal **and** the service fee |

* The service fee is refunded only on a full refund with `feeType: "include_fee"`. Partial refunds return principal only.
* If you refunded the principal without the fee, send another refund with `feeType: "include_fee"` and no `amountCents` to refund the fee.
* Asking for more principal than remains returns `422 INVALID_STATE`; `message` gives the remaining amount in cents.
* `reason` is optional (up to 1000 characters).

## `reversalType`

The response's `reversalType` identifies whether the payment was voided or refunded:

* `"void"` means the payment had not settled and was voided.
* `"refund"` means the payment had settled and was refunded.

The API selects the operation based on settlement status.

## Amounts after a refund

On the payment (`GET /payments/{id}`):

* `refundedAmountCents` is the total refunded so far, including principal and service fee.
* `remainingRefundableAmountCents` is the amount still refundable, including principal and service fee.
* `status` is `partially_refunded` until the principal and service fee have both been fully refunded. It then becomes `refunded`.

## Example: full refund including the fee

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://apistagepc.grogov.us/api/partner/v1/payments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/refund \
    -H "Authorization: ApiKey pc_<your-key>" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{ "feeType": "include_fee", "reason": "Case dismissed" }'
  ```

  ```js Node.js theme={null}
  const res = await fetch(
    "https://apistagepc.grogov.us/api/partner/v1/payments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/refund",
    {
      method: "POST",
      headers: {
        Authorization: "ApiKey pc_<your-key>",
        "Content-Type": "application/json",
        "Idempotency-Key": crypto.randomUUID(),
      },
      body: JSON.stringify({ feeType: "include_fee", reason: "Case dismissed" }),
    }
  );
  const data = await res.json();
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "target": "group",
    "reversalType": "refund",
    "amountCents": 10300,
    "currency": "USD",
    "reason": "Case dismissed",
    "status": "succeeded",
    "remainingRefundableAmountCents": 0,
    "gateway": { "transactionId": "4938271649" },
    "createdAt": "2024-03-01T12:00:00.000Z"
  }
}
```

`target` is always `"group"`, indicating that the refund applies to the payment. Individual line items cannot be refunded separately.

`amountCents` is the amount returned by this refund. In this example, it includes 10000 cents of principal and a 300-cent service fee.

## Example: partial refund

```bash cURL theme={null}
curl -X POST https://apistagepc.grogov.us/api/partner/v1/payments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/refund \
  -H "Authorization: ApiKey pc_<your-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "amountCents": 2500, "reason": "Partial fine waiver" }'
```

## When the fee refund fails

If the principal refund succeeds but the separate service-fee refund fails, you get `502 PARTIAL_REFUND_PENDING` with `details.remainingRefundableAmountCents`. Retry the same refund to finish it. See [Errors](/guides/errors).

## Line items

Each line item in the payment response carries its `amountCents`, its pro-rated share of the service fee (`serviceFeeCents`), and your `referenceId`, `description` and `metadata`. Use them for reconciliation and display.

## Idempotency

Refunds support the `Idempotency-Key` header, so retries are safe. See [Idempotency](/guides/idempotency).


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