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

# Create a refund

`POST /v1/refunds`

## Request

- Base URL: `https://scl-sandbox.dev.clover.com`
- URL: `https://scl-sandbox.dev.clover.com/v1/refunds`
- Auth: OAuth 2
  - Authorization code: `https://sandbox.dev.clover.com/oauth/authorize`
  - Token URL: `https://sandbox.dev.clover.com/oauth/token`

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.dev/clover/apis/ecommerce-service-api.md) - [All operations](https://skmtc.dev/clover/apis/ecommerce-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clover/apis/ecommerce-service-api/revisions/a0aeb344ed80?raw)