> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/remittance-api/business/payment/payment-refund-notification.md).

# Payment Refund Notification

Notifies the partner when a payment order changes status and provides the settlement, fee, refund, and error details required for reconciliation.

Notifies the partner when funds are returned for a payment order.

### Notification delivery

Pagsmile sends an HTTP POST request to your configured webhook URL.

Content-Type: application/json; charset=UTF-8

The notification uses the [Webhook Common envelope](https://docs.pagsmile.com/remittance-api/common/webhook-common). The fields below describe the decrypted `biz_data` object.

Webhook notify\_type: 211.

{% hint style="info" %}
**Requirement:** `M` = Mandatory, `O` = Optional, and `C` = Conditional. A conditional field is mandatory only when the condition stated in its description applies.
{% endhint %}

### Notification body

The following fields describe the decrypted biz\_data object.

<table><thead><tr><th width="205.2109375">Field</th><th width="105.6640625">Type</th><th width="109.33203125">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>merchant_id</code></td><td>long</td><td>M</td><td>Pagsmile-assigned unique identifier of the merchant.</td></tr><tr><td><code>payment_id</code></td><td>long</td><td>M</td><td>Pagsmile-assigned unique identifier of the original payment order.</td></tr><tr><td><code>payment_amount</code></td><td>string</td><td>M</td><td>Original payment amount, expressed in payment_currency.</td></tr><tr><td><code>payment_currency</code></td><td>string</td><td>M</td><td>Three-letter ISO 4217 code of the original payment order currency.</td></tr><tr><td><code>refund_transaction_id</code></td><td>long</td><td>M</td><td>Pagsmile-assigned unique identifier of the accounting transaction created for the payment refund.</td></tr><tr><td><code>refund_amount</code></td><td>string</td><td>M</td><td>Amount returned for the payment, expressed in refund_currency.</td></tr><tr><td><code>refund_currency</code></td><td>string</td><td>M</td><td>Three-letter ISO 4217 code of the refund currency.</td></tr><tr><td><code>return_fee</code></td><td>string</td><td>O</td><td>Fee returned as part of the payment refund, expressed in refund_currency.</td></tr><tr><td><code>refunded_at</code></td><td>string</td><td>M</td><td>Date and time when the payment refund was completed.<br>Format: yyyy-MM-dd HH:mm:ss.</td></tr><tr><td><code>refund_reason</code></td><td>string</td><td>O</td><td>Reason provided for the payment refund.</td></tr></tbody></table>

### Plaintext biz\_data example

```json
{
  "merchant_id": 100398,
  "payment_id": 200001,
  "payment_amount": "100.00",
  "payment_currency": "USD",
  "refund_transaction_id": 300001,
  "refund_amount": "100.00",
  "refund_currency": "USD",
  "return_fee": "0.00",
  "refunded_at": "2026-10-26 10:35:00",
  "refund_reason": "Payment returned by the beneficiary bank"
}
```

### Acknowledgement

Return any HTTP 2xx status code after the notification is safely recorded. Process repeated notifications idempotently using the webhook request\_id. For delivery, retries, and signature handling, refer to Webhook Common.
