---
title: "Refund a payment"
method: POST
path: "/payments/{id}/refunds"
tags: ["Payments"]
---

# Refund a payment

`POST /payments/{id}/refunds`

## Request

- Base URL: `https://{prefix}.api.sandbox.checkout.com`
- URL: `https://{prefix}.api.sandbox.checkout.com/payments/{id}/refunds`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `string` scopes: `gateway`, `gateway:payment-refunds`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/payments/:id/refunds/post.ts> (a function with typed inputs; its response is checked against the schema)

Refunds a payment if supported by the payment method.

For card payments, refund requests are processed asynchronously. You can use [workflows](#tag/Workflows) to be notified if the refund is successful.

## Path parameters

- `id` string, required

## Headers

- `Cko-Idempotency-Key` string

## Request body

- RefundRequest
  - `amount` integer: The amount to refund. If not specified, the full payment amount will be refunded.
  - `reference` string: A reference you can later use to identify this refund request.<br>For Amex, the string limit is 30 characters. <br> For TWINT, the string limit is 50 characters.
  - `amount_allocations` object[]: The sub-entities that the payment is being processed on behalf of
    - `id` string, required: The id of the sub-entity.
    - `amount` integer, required: The split amount - this will be credited to your sub-entity's currency account. The sum of all split amounts must be equal to the payment amount. The amount must be provided in the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="blank">minor currency unit</a>.
    - `reference` string: A reference you can later use to identify this split, such as an order number.
    - `commission` object: Commission you'd like to collect from this split - this will be credited to your currency account. The commission cannot exceed the split amount. Commission = (`amount` * `commission.percentage`) + `commission.amount`
      - `amount` integer: Optional fixed amount of commission to collect. The amount must be provided in the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="blank">minor currency unit</a>.
      - `percentage` number: Optional percentage of commission to collect. Supports up to 8 decimal places.
  - `capture_action_id` string: The Checkout.com action ID of the capture you want to refund. Only for PayPal and Riverty.
  - `items` object[]: The order's line items.
    - `type` 'digital' | 'discount' | 'physical': The item type. For example, `physical` or `digital`. This field is used to provide item level metadata where applicable. If `source.type` is `sequra`, this field is required.
    - `sub_type` 'blockchain' | 'cbdc' | 'cryptocurrency' | 'nft' | 'stablecoin': The digital item type. If `type` is set to `digital`, this field is required.
    - `name` string: The descriptive name of the line item. If `source.type` is `sequra`, this field is required.
    - `quantity` integer: The number of line items. If `source.type` is `sequra`, this field is required.
    - `unit_price` integer: The unit price of the item the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="blank">minor currency unit</a>. Required if `source.type` is `sequra`
    - `reference` string: The item reference or product SKU (stock-keeping unit). For Visa and Mastercard's interchange reduction programs, this value has a maximum length of 12 characters. If `source.type` is `sequra`, this field is required.
    - `commodity_code` string: A code identifying a Commodity for value-added tax (VAT) purposes.
    - `unit_of_measure` string: Unit of Measure code used for an item in transaction.
    - `total_amount` number: The total cost of the line item, in <a href="https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value" target="_blank">minor currency units</a>. Calculate this using the following formula: `total_amount` = (`quantity` * `unit_price`) - `discount_amount`. If `source.type` is `sequra`, this field is required.
    - `tax_rate` number: The tax rate of the item line in minor units. The percentage value is represented with two implicit decimals. For example, 2000=20%.
    - `tax_amount` number: Contains the total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase.
    - `tax_exempt` boolean: Indicates whether the products or services are tax-exempt. <p/> Set to `true` if: - You are processing a card payment. - The `tax_amount` field is `0` due to a tax-exempt product or service.
    - `discount_amount` number: The discount applied to each invoice line item.
    - `wxpay_goods_id` string: Unified product No. defined by WeChat Pay
    - `url` string: Link to the line item's product page
    - `image_url` string: Link to the line item's product page
    - `service_ends_on` string, date: Maximum date for the service to be rendered or ended. If `source.type` is `sequra` and `item.type` is `digital`, this field is required.
    - `purchase_country` string: The country where the purchase was made. <br/>Format – <a href="https://www.checkout.com/docs/previous/resources/codes/country-codes" target="_blank">ISO alpha-2 country code</a>
    - `foreign_retailer_amount` integer: The foreign retailer amount the merchant applied to the transaction, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value).
  - `destination` RefundBankAccountDestination: The destination of the refund. This field is required for giropay and EPS refunds.
    - `account_type` 'savings' | 'current' | 'cash': The type of account to which the refund will be sent.
    - `account_number` string, required: The account number.
    - `bank_code` string, required: The code that identifies the bank.
    - `branch_code` string: The code that identifies the bank branch.
    - `iban` string: The account's International Bank Account Number (IBAN).
    - `bban` string: The account's Basic Bank Account Number (BBAN). The BBAN is a combination of the account number and the bank or branch code, or both.
    - `swift_bic` string: An 8 or 11-digit code that identifies the bank or bank branch.
    - `country` string, required: The two-letter <a href="https://www.checkout.com/docs/resources/codes/country-codes" target="_blank">ISO country code</a> of the country where the account is based.
    - `account_holder` RefundDestinationAccountHolder, required: The account holder details.
      - `type` 'individual' | 'corporate' | 'government': The account holder type.
      - `first_name` string, required: The account holder's first name.
      - `last_name` string, required: The account holder's last name.
      - `company_name` string: The corporate account holder's company name.
      - `tax_id` string: The account holder's tax number or reference.
      - `date_of_birth` string, date: The account holder's date of birth, in the format `YYYY-MM-DD`.
      - `country_of_birth` string: The two-letter <a href="https://www.checkout.com/docs/resources/codes/country-codes" target="_blank">ISO country code</a> of the account holder's country of birth.
      - `residential_status` 'resident' | 'non_resident': The account holder's residential status.
      - `billing_address` Address
        - `address_line1` string: The first line of the address.
        - `address_line2` string: The second line of the address. <p/> For SEPA payments, this value has a maximum length of 10 characters.
        - `city` string: The address city.
        - `state` string: The state or province of the address country <a href="https://en.wikipedia.org/wiki/ISO_3166-2" target="_blank">ISO 3166-2 code</a> (for example: CA for California in the United States).
        - `zip` string: The address zip or postal code.
        - `country` string: The two-letter <a href="https://www.checkout.com/docs/resources/codes/country-codes" target="_blank">ISO country code</a> of the address.
      - `phone` PhoneNumber: A phone number
        - `country_code` string: The international <a href="https://www.checkout.com/docs/resources/codes/country-codes" target="_blank">country calling code</a>. Required if `source.type` is `tamara`.
        - `number` string: The phone number. Required if `source.type` is `tamara`.
      - `identification` AccountHolderIdentification: Bank account holder's proof of identification
        - `type` 'passport' | 'driving_licence' | 'national_id' | 'company_registration' | 'tax_id': The type of identification used to identify the account holder
        - `number` string: The identification number
        - `issuing_country` string: The two-letter <a href="https://www.checkout.com/docs/resources/codes/country-codes" target="_blank">ISO country code</a> of the country that issued the identification
      - `email` string, email: The account holder's email address.
    - `bank` BankDetails: Details of the bank
      - `name` string: The bank's name
      - `branch` string: The bank branch's name
      - `address` Address
        - `address_line1` string: The first line of the address.
        - `address_line2` string: The second line of the address. <p/> For SEPA payments, this value has a maximum length of 10 characters.
        - `city` string: The address city.
        - `state` string: The state or province of the address country <a href="https://en.wikipedia.org/wiki/ISO_3166-2" target="_blank">ISO 3166-2 code</a> (for example: CA for California in the United States).
        - `zip` string: The address zip or postal code.
        - `country` string: The two-letter <a href="https://www.checkout.com/docs/resources/codes/country-codes" target="_blank">ISO country code</a> of the address.
  - `metadata` object: A set of key-value pairs to attach to the authorization request. You can use this to store additional information in a structured format. The `metadata` object only supports primitive data types. Objects and arrays are not supported.

## Response `200`

Payment is already refunded

- object: The response received when you attempt a repeated payment action. For example, if you attempt to refund a payment that is already refunded.
  - `action_id` string, required: The action identifier
  - `_links` object: Links related to the payment.
    - `payment` Link, required
      - `href` string, required: The link URL

## Other responses

- `202`: Refund accepted
- `401`: Unauthorized
- `403`: Refund not allowed
- `404`: Payment not found
- `422`: Invalid data was sent
- `429`: Too Many Requests
- `502`: Bad gateway

---

[API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)