> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds

> Return a pay-in to the payer.

A refund sends a pay-in back to the person who paid. You can refund a successful pay-in yourself. Payve also creates refunds automatically when a payment link is overpaid or underpaid.

## What a refund returns

A refund you request returns the **full amount the payer sent**: the pay-in's `amount`, not the net amount that reached your wallet. Fees you were charged on the pay-in are yours to carry.

* Refunds are for the whole pay-in. There is no partial refund.
* A pay-in can be refunded once.
* The refund goes back on the same kind of rail the payment came in on.

## Refund a pay-in

`POST /v1/refunds` · needs the `payouts:write` scope

**payinPublicId** `string` *required*

The `publicId` of the pay-in, such as `pin_3f9a2c1d8e7b6a50`.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/refunds" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payinPublicId": "pin_3f9a2c1d8e7b6a50" }'
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/refunds`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ payinPublicId: 'pin_3f9a2c1d8e7b6a50' }),
});
const { data: refund } = await res.json();
```

```python Python
import os, requests

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/refunds",
    headers={"x-api-key": os.environ["PAYVE_API_KEY"]},
    json={"payinPublicId": "pin_3f9a2c1d8e7b6a50"},
)
refund = res.json()["data"]
```

```json Response · 201
{
  "data": {
    "id": 412,
    "publicId": "ref_8c1e5a9d3b7f2046",
    "payinTransactionId": 1851,
    "payoutTransactionId": null,
    "merchantId": 318,
    "amount": "5000000",
    "currency": "NGN",
    "status": "awaiting_recipient",
    "reason": "merchant_initiated",
    "recipientInfo": null,
    "message": "Please provide recipient details to complete the refund.",
    "attempt": 1,
    "createdAt": "2026-11-18T13:00:00.000Z",
    "updatedAt": "2026-11-18T13:00:00.000Z"
  }
}
```

**publicId** `string`

The `ref_` id. Use it in refund URLs.

**amount** `string`

The amount being refunded, in minor units.

**status** `string`

Where the refund is. See the table below.

**reason** `string`

`merchant_initiated`, `overpayment` or `underpayment`.

**recipientInfo** `object | null`

Where the refund is going.

**message** `string | null`

What the refund is waiting for, in plain words.

**payoutTransactionId** `integer | null`

The payout that carries the refund, once it has been sent.

Only a pay-in that succeeded can be refunded.

Asking to refund the same pay-in again returns the refund that already exists.

## Refund statuses

| Status | Meaning | Final? |
| - | - | - |
| `awaiting_recipient` | Payve needs to know where to send the money. | No |
| `awaiting_approval` | The destination is known. Payve is reviewing the refund before it goes. | No |
| `processing` | The refund is on its way. | No |
| `succeeded` | The payer has the money. | Yes |
| `failed` | The refund payout failed. | Yes |
| `rejected` | Payve's review declined the refund. No money moved. | Yes |

> [!NOTE]
>
> Refunds use `succeeded`, not `successful`. Do not reuse your transaction status handling for them.

## When the destination is known

For a bank transfer, the bank usually tells Payve which account paid. Payve stores it as `senderDetails` on the pay-in and uses it for the refund. The refund then starts in `processing` with `recipientInfo` filled in, and you do nothing more.

## When the destination is not known

The refund starts in `awaiting_recipient`. Supply the destination:

`POST /v1/refunds/{id}/process` · needs the `payouts:write` scope

```bash
curl -X POST "$PAYVE_API_URL/v1/refunds/ref_8c1e5a9d3b7f2046/process" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientInfo": {
      "accountNumber": "0123456789",
      "accountName": "Chidi Okeke",
      "bankCode": "058",
      "bankName": "Guaranty Trust Bank"
    }
  }'
```

For a mobile money refund, send `phoneNumber` and `operator` instead of the bank fields.

> [!WARNING]
>
> **You can set the destination once.** A second submission for the same refund is refused. Run a
> [name check](/guides/name-check.md) on the account and confirm it with the payer before you send it.
> Money refunded to the wrong account is not something Payve can pull back.

## Automatic refunds from payment links

When a fixed-amount payment link is overpaid or underpaid beyond your tolerances, Payve creates the refund for you with a `reason` of `overpayment` or `underpayment`. See [Overpayment and underpayment](/guides/payment-links.md#overpayment-and-underpayment).

These refunds wait in `awaiting_approval` for Payve's review, or in `awaiting_recipient` if the paying account is not known. In that case the hosted checkout asks the payer for the destination.

## Track a refund

There is no webhook event for refunds. Fetch the refund to follow it.

| Request | Returns |
| - | - |
| `GET /v1/refunds/{id}` | One refund, by its `ref_` id. |
| `GET /v1/refunds` | All your refunds. |
| `GET /v1/refunds?payinTransactionId=1851` | The refunds for one pay-in. |

> [!TIP]
>
> Poll a refund that is `processing` every few minutes until it is `succeeded` or `failed`. Do not
> tell the payer it has arrived before `succeeded`.

## When it fails

| Status and code | Cause | Fix |
| - | - | - |
| `403 forbidden` | The key lacks `payouts:write`, or API money movement is off. | Use a key with the scope. |
| `404 resource_not_found` | The pay-in or refund is not on your account. | Check the id. Use the pay-in's `publicId`. |
| `5xx` | The pay-in is not in a refundable state, or a destination was already submitted. | Fetch the pay-in and the refund and read their statuses. Do not retry blindly. |
