---
updatedAt: 2026-09-04T05:48:22.000Z
agentTools:
  projectIndex: https://docs.paymongo.com/llms.txt
---

# Refunds

How to issue full or partial refunds via API or dashboard, timelines by payment method, and restrictions that apply.

## Overview

Refunds return funds to a customer for a completed payment. Only payments with a `paid` status can be refunded.

If your upcoming payout balance is insufficient to cover a refund, the request will not go through until the balance is replenished. Refunds for already-paid-out transactions are deducted from your next payout.

***

## Refund a payment

**Via the dashboard**

1. Go to **Links** or **Payments** in your PayMongo dashboard
2. Select the payment you want to refund
3. Click **Refund**
4. Choose full or partial refund, select a reason, and add an optional note

**Via the API**

You can issue a full refund by setting `amount` equal to the original payment amount, or a partial refund by setting it to any lesser value. Multiple partial refunds can be issued on the same payment as long as the total doesn't exceed the original.

```javascript
const refund = await fetch('https://api.paymongo.com/v1/refunds', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa('sk_test_YOUR_SECRET_KEY:')
  },
  body: JSON.stringify({
    data: {
      attributes: {
        amount: 10000,
        payment_id: 'pay_xxx',
        reason: 'others',
        notes: 'Customer requested refund for order cancellation'
      }
    }
  })
}).then(r => r.json());
```

| Parameter    | Required | Description                                                                  |
| ------------ | -------- | ---------------------------------------------------------------------------- |
| `amount`     | Yes      | Amount in centavos. Must be ≤ original payment amount minus previous refunds |
| `payment_id` | Yes      | The ID of the payment to refund                                              |
| `reason`     | Yes      | One of: `duplicate`, `fraudulent`, `others`                                  |
| `notes`      | No       | Internal notes for your records                                              |

***

## Eligibility and timelines by payment method

| Payment method                     | Refund window | Partial refunds                  | Time to reflect                                                                     |
| ---------------------------------- | ------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
| Debit / Credit Card                | 60 days       | Yes (full only for installments) | Up to 30 days                                                                       |
| GCash                              | 180 days      | Yes                              | Within 24 hours                                                                     |
| GrabPay                            | 90 days       | Yes                              | Within 24 hours                                                                     |
| Maya                               | 12 months     | Yes\*                            | Within 24 hours                                                                     |
| ShopeePay                          | 365 days      | Yes                              | Within 24 hours                                                                     |
| BPI Online Banking                 | 30 days       | Yes                              | At least 3 banking days                                                             |
| BillEase                           | 60 days       | Yes                              | Within 24 hours                                                                     |
| BDO, Metrobank, Landbank (Brankas) | 30 days       | Yes                              | Up to 5 banking days†                                                               |
| QR Ph                              | 30 days       | Yes                              | If less than PHP 50,000 - Real time<br />If more than PHP 50,000 - Next banking day |
| UBP Online Banking                 | —             | No                               | —                                                                                   |

\*Maya partial refunds: only a full refund is allowed on the same day. Partial refunds can only be filed starting 12:00 AM the following day.

Brankas refunds are deposited to the merchant's bank account. The merchant is responsible for settling directly with the customer.

QR P&#x68;**&#x20;**&#x72;efunds feature is accessible via **Dashboard** from Payments and via **API**.&#x20;

**UBP Online Banking payments cannot be refunded.** If a customer paid via one of these methods, contact <support@paymongo.com>.

***

## Refund errors

If a refund request fails, check the error code in the API response:

* `payment_not_found` — the `payment_id` doesn't exist or isn't in your account
* `refund_amount_exceeds_payment` — the requested amount exceeds what's available to refund
* `payment_not_refundable` — the payment is in a state that doesn't allow refunds (e.g., still `processing`)

For a complete list of error codes, see the API Reference.