---
title: "Create a refund"
method: POST
path: "/v1/refunds"
tags: ["REFUNDS"]
---

# Create a refund

`POST /v1/refunds`

Creates a new refund that must be associated with an existing charge. Refunds are applied to the `source` used for the original payment. Partial refunds are allowed up to the original charge amount.

## Headers

- `User-Agent` string, required

## Request body

- object
  - `charge` string, required — Unique identifier (ID) of the charge to refund. The `charge` parameter is available in the [Get charges](https://docs.clover.com/reference/getcharges) and [Get a charge](https://docs.clover.com/reference/getchargescharge) endpoints.
  - `amount` integer — Refund amount in cents from the remaining, unrefunded amount of the charge.
  - `external_reference_id` string — Unique dentifier (ID), such as an invoice or purchase order (PO) number, that is passed to the merchant's gateway and displays in settlement records. Format: Supported for US—alphanumeric characters with in-between spaces Length: Max 12, including spaces and alphanumeric characters.
  - `reason` 'duplicate' | 'fraudulent' | 'requested_by_customer' — Reason for the refund.

## Response `200`

Successful response. Refund created.

- Refund
  - `id` string, required — Refund identifier.
  - `amount` integer, required — Refund amount from the balance of unrefunded amount of the charge. Format: Cents
  - `additional_charges` AdditionalCharges, required — Additional surcharge or other fee applied on the transaction.
    - `amount` integer — Amount of the additional charges applied on the transaction. Format: Cents
    - `id` string — Unique identifier of the additional charge.
    - `rate` integer — Item-specific tax of an additonal charge where a 10% rate is defined as 1000000.
    - `type` 'CREDIT_SURCHARGE' — Type of the additional charge collected on the transaction.
  - `created` integer, required — Displays results based on the object's created field. Values: String with a Unix timestamp (in milliseconds). Dictionary of multiple options describing a time range.
  - `currency` string, required — Three-letter [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html).
  - `description` string — Description about the refund.
  - `external_reference_id` string — Unique identifier (ID), such as an invoice or purchase order (PO) number, that is sent to the merchant's gateway and displayed in settlement records. Format: Supported for US—alphanumeric characters with in-between spaces. Length: Max 12, including spaces and alphanumeric characters.
  - `failure_reason` 'lost_or_stolen_card' | 'expired_or_canceled_card' | 'unknown' — Reason of the cancellation of the refund.
  - `charge` string, required — Charge identifier.
  - `metadata` object, required — Indicates whether a US merchant with the gateway group Ids 40001 or 10001, and merchant category codes (MCC) 6012 or 6051 can process Visa® consumer debit transactions that have an existing debt. Values: True - Merchant can process transactions that have an existing debt. False - Default; Transactions do not have an existing debt.
  - `object` 'refund', required — Object of the refund.
  - `reason` 'duplicate' | 'fraudulent' | 'requested_by_customer', nullable — Reason for the refund.
  - `receipt_number` string, nullable — Transaction receipt number that appears on the receipt emailed for this charge
  - `status` 'succeeded (card or non-card)' | 'failed (card or non-card)' | 'pending (non-card only)' | 'canceled (non-card only)', nullable, required — Status of the refund. Values: For credit cards - succeeded or failed For other methods - pending, succeeded, failed, or canceled

## Other responses

- `default` — Error response.

---

[API](https://skmtc.net/clover/apis/platform-api.md) · [All operations](https://skmtc.net/clover/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clover/platform-api/revisions/08da265101a3/schema)