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

# Refund a payment

`POST /v2/payments/{payment_id}/refunds`

## Request

- Base URL: `https://api.getpaid.io`
- URL: `https://api.getpaid.io/v2/payments/{payment_id}/refunds`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.getpaid.io/oauth/token` scopes: `payments:read_write`
- TypeScript: <https://skmtc.dev/getpaid/apis/getpaid-api/docs/v2/payments/:payment_id/refunds/post.ts> (a function with typed inputs; its response is checked against the schema)

Refund a captured payment fully or partially.

Related webhooks:

- [`payment_refunded`](#tag/Accept-payments-webhooks/operation/payment_refunded): sent when the funds are returned to the buyer.
- [`payment_refund_failed`](#tag/Accept-payments-webhooks/operation/payment_refund_failed): sent when a refund process fails due to business or technical issues.

## Path parameters

- `payment_id` string, id, required: The unique identifier of the payment.

## Headers

- `Getpaid-Idempotency-Key` string, required

## Request body

- union
  - FullRefundPaymentRequest
    - `type` 'full' | 'partial', required: The type of refund to be processed.
    - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `webhooks` object: Configuration for webhooks to receive refund status updates.
      - `url` string, uri, required: The URL to which webhook events will be sent.
  - PartialRefundPaymentRequest
    - `type` 'full' | 'partial', required: The type of refund to be processed.
    - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
    - `splits` object, required: The list of refund splits for the accounts involved in the funds flow.
      - `accounts` RefundSplitAccount[], required: The list of accounts involved in the refund that will return the funds. All the accounts involved in the original payment receiving funds must be included even if they did not receive funds in the payment or they are not returning funds in the refund.
        - `id` string, id, required: The unique identifier of the account.
        - `split` object, required: The amount in the payment currency to return from this account.
          - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
    - `webhooks` object: Configuration for webhooks to receive refund status updates.
      - `url` string, uri, required: The URL to which webhook events will be sent.

## Response `201`

Created

- union
  - FullRefundPaymentResponse
    - `id` string, id, required: The unique identifier of the refund of a payment.
    - `type` 'full' | 'partial', required: The type of refund to be processed.
    - `status` 'initiated' | 'completed' | 'declined' | 'failed', required: The status of the refund payment. See the [list, transitions, and description of each status](/payments/refunds/lifecycle) for more details.
    - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `created_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
    - `updated_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
    - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
    - `splits` object, required: The list of refund splits for the accounts involved in the funds flow from the original payment.
      - `accounts` RefundSplitAccount[], required: The list of accounts involved in the original payment with the funds they are going to return to the buyer.
        - `id` string, id, required: The unique identifier of the account.
        - `split` object, required: The amount in the payment currency to return from this account.
          - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
  - PartialRefundPaymentResponse
    - `id` string, id, required: The unique identifier of the refund of a payment.
    - `type` 'full' | 'partial', required: The type of refund to be processed.
    - `status` 'initiated' | 'completed' | 'declined' | 'failed', required: The status of the refund payment. See the [list, transitions, and description of each status](/payments/refunds/lifecycle) for more details.
    - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `created_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
    - `updated_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found
- `409`: Conflict
- `422`: Invalid Parameters
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/getpaid/apis/getpaid-api.md) - [All operations](https://skmtc.dev/getpaid/apis/getpaid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpaid/apis/getpaid-api/revisions/776466b63d14?raw)