---
title: "Create Refund"
method: POST
path: "/refund"
tags: ["Refund"]
---

# Create Refund

`POST /refund`

## Request

- Base URL: `https://api.finmo.net/v1`
- URL: `https://api.finmo.net/v1/refund`
- Auth: HTTP basic

Refund of a Payin. When the Payin status is `completed`, you can issue a full or partial refund of the collected amount. Whether a Payin Method is eligible for a refund or not depends on the ```is_refundable``` field returned by [Get Required Fields by Payin Method](/reference/getrequiredfieldsbypayinmethod-1).

If a refund is made on a Payin that has already been settled, you must ensure sufficient balance in your Payin wallet. There are two options:

1.  **Wait for Incoming Funds:** Wait for more funds from customers to accumulate in your Payin wallet before initiating a refund.
  
2.  **Fund Your Payin Wallet:**
  
  *   **Create a Checkout:** Fund your Payin wallet by creating a checkout.
      
  *   **Load Funds Using a Virtual Account:** Load funds into your Organization's Payin wallet using a Virtual Account (if supported by the specific Payin Method). Note that top-up via virtual account will not incur a fee, but using a checkout page will incur a nominal fee, as the system cannot differentiate if it is a top-up transaction or a transaction initiated by the end customer.
      

The refund process will check the available balance in your Payin wallet and, upon success, will debit the wallet. Finmo will debit the fee plus taxes from your next settlement if the settlement option is NET, otherwise, it will be added to your monthly invoice.

The refund process will hold the needed funds in your Payin wallet and debit them once the refund is successful.

### Checking Support for Partial-Refund or Over-Refund

Some Payin Methods support options for 'partial-refund' or 'over-refund' (refunding more than the original transaction amount). These capabilities are indicated by binary flags:

*   **is_partially_refundable:** Indicates if partial refunds are supported.
  
*   **is_over_refundable:** Indicates if over-refunds are supported.
  

These flags are returned in the response of the [Get Required Fields by Payin Method](/reference/getrequiredfieldsbypayinmethod-1) API.

Currently, Finmo platform does not support the over-refund option.

## Request body

- object
  - `payin_id` string, required: Payin reference (payin_*)
  - `type` 'FULL' | 'PARTIAL', required: FULL or PARTIAL Default type is 'FULL'. In case of 'PARTIAL' refund, please provide the amount & currency
  - `amount` number, required: **Conditionally required:** Refund amount if type is 'partial'. The number of decimal place will be different for each currency according to ISO 4217
  - `currency` string, required: **Conditionally required:** Reason for refund can be provided in the description
  - `organization_reference_id` string: A reference you can later use to identify this payment, such as an order number. Can only be alphanumeric and must be unique for Benefit. By default, Payin's organization_reference_id will apply.
  - `webhook_url` string: Custom webhook url for this refund. If not provided we will notify you on whats configured on the Dashboard
  - `metadata` object: Custom Data

## Response `200`

OK

- object
  - `data` object
    - `amount` integer
    - `created_at` string, date-time
    - `currency` string
    - `customer_id` string, nullable
    - `debit_wallet_id` string
    - `debit_wallet_transaction_id` string
    - `description` string, nullable
    - `fees_currency` string, nullable
    - `fees_including_tax` string, nullable
    - `fees_wallet_id` string
    - `fees_wallet_transaction_id` string, nullable
    - `fees_without_tax` string, nullable
    - `is_fees_charged` boolean
    - `metadata` string, nullable
    - `org_id` string
    - `organization_reference_id` string
    - `payin_id` string
    - `payin_method_name` string
    - `receipt_email` string, nullable
    - `refund_id` string
    - `refunded_at` string, date-time, nullable
    - `status` string
    - `tax_on_fees` string, nullable
    - `transaction_id` string, nullable
    - `type` string
    - `updated_at` string, date-time
    - `webhook_url` string, uri, nullable
  - `request_id` string
  - `request_time` string, date-time
  - `status_code` integer
  - `status_text` string
  - `success` boolean

## Other responses

- `400`: Bad Request
- `406`: Not Acceptable

## Changes

- **2026-11-03** `39e5e5ab5c3a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/finmo/apis/finmo-api/changes/refund/post.md)

---

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