---
title: Refund a payment
description: Return all or part of a successful payment from your disbursement account. Needs the refund permission.
api: POST /payments/{reference}/refund
---

Creates a `pending` refund (`type: refund`) of the collection in the path. The money goes back to the number that paid. See [Refund payments](/docs/guides/refunds).

Refunds can never add up to more than the original; pending refunds count towards that.

- **`reference`** · path · `string` · required

  The `external_reference` of the collection to refund.

- **`external_reference`** · body · `string` · required

  A new reference for the refund itself. Retrying with it returns the original refund.

- **`amount`** · body · `number`

  How much to refund. Leave it out to refund everything that's left.

- **`description`** · body · `string`

  Shown in both parties' transaction history. Defaults to `Refund <reference>`.

- **`metadata`** · body · `object`

  Your own data.

## Response

A [transaction](/docs/concepts/transactions#the-transaction-object) with `type: refund`, `status: pending` and `refund_of` set to the original's reference.

```json 200
{
  "success": true,
  "message": "refund initiated",
  "data": {
    "external_reference": "order-1001-refund-1",
    "type": "refund",
    "direction": "out",
    "provider_id": "momo",
    "amount": 10,
    "currency": "SZL",
    "status": "pending",
    "payee_phone": "26876123456",
    "description": "Partial refund, item out of stock",
    "refund_of": "order-1001",
    "metadata": {},
    "created_at": 1760860800,
    "updated_at": 1760860800
  }
}
```

```json 400
{ "success": false, "message": "refund exceeds the amount left to refund", "data": null }
```

Other `400` messages: `only successful collections can be refunded`, `only payments collected with a payment request can be refunded`, and `the momo disbursement account is not connected, so payouts and refunds are unavailable`.