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

# Refund ingestion

> Record refunds made directly with your payment service on the matching Gr4vy transaction.

Refunds you create through the Gr4vy API or dashboard are recorded on the transaction. A refund made directly with the payment service, for example in its own dashboard, isn't. The transaction's `refunded_amount` then no longer matches what the payment service holds.

Refund ingestion closes that gap. When a supported payment service reports a refund that Gr4vy didn't initiate, Gr4vy records it on the transaction it belongs to.

Refund ingestion is off by default. You turn it on for each connection.

## Turn on refund ingestion

The setting only appears on connections whose payment service supports refund ingestion. See [supported connectors](#supported-connectors).

1. In the dashboard, go to **Connections** -> **Configured connections** and select the connection.
2. Under **Ingest refunds**, select **Enabled**.
3. Save your changes.

Turn it on for the connection that processes the payments. Gr4vy only records a refund on a transaction that the same connection processed.

Gr4vy records the refunds that the payment service reports after you turn the setting on. Refunds reported before then aren't recorded.

## How an ingested refund behaves

From the moment it's recorded, an ingested refund is an ordinary Gr4vy refund. It has the same effects as a refund you create through Gr4vy:

* Gr4vy sends a `refund.succeeded` webhook.
* The refund amount is added to the transaction's `refunded_amount`, so less of the transaction remains available to refund.
* The refund appears on the transaction in the dashboard and in [list transaction refunds](https://integration.wpay.com.au/reference/transactions/list-transaction-refunds.md). Its `payment_service_refund_id` is the payment service's ID for the refund.

Gr4vy doesn't move any money for an ingested refund. The payment service has already made the refund, and Gr4vy only records it as succeeded.

## Limitations

* Gr4vy only records a refund on a captured transaction it already holds. A refund for a payment that wasn't processed through Gr4vy is ignored.
* Only successful refunds are recorded. A pending, declined, or failed refund made outside Gr4vy isn't recorded.
* The refund amount can't exceed the amount that's still refundable on the transaction. A larger refund isn't recorded.

## Supported connectors

The following connectors support refund ingestion.

Worldpay (VAP) is currently the only connector that needs extra setup. Worldpay doesn't notify Gr4vy of refunds, so you report each one yourself. See [report refunds made with Worldpay](https://integration.wpay.com.au/connections/payments/worldpayvap-card#report-refunds-made-with-worldpay).

## Webhooks and transaction events

Gr4vy sends a `refund.succeeded` webhook for an ingested refund. The payload is the same as for a refund you created through Gr4vy. See [webhook events](https://integration.wpay.com.au/guides/features/webhooks/events.md).

The transaction's history in the dashboard and in [list transaction events](https://integration.wpay.com.au/reference/transactions/list-transaction-events.md) also records the ingested refund:

* A **Webhook processed** event, for the notification that reported the refund.
* An **External refund reported** event, named `refund-ingested` in the API. It shows the refund, the payment service's ID for the refund, the amount, and the payment service.

The event's **Outcome** is **Created** for a refund made outside Gr4vy. **Adopted** means the payment service reported a refund that Gr4vy had already created, and Gr4vy added the payment service's refund ID to it. An adopted refund isn't a new refund, and it can appear even when refund ingestion is off. Count only **Created** events as refunds made outside Gr4vy.

## Testing

In sandbox, the card simulator and the PayPal simulator support refund ingestion. They accept a `refund.succeeded` payload that names a transaction instead of a Gr4vy refund, and Gr4vy treats it as a refund made outside Gr4vy.

1. Turn on **Ingest refunds** on the simulator connection.
2. Create and capture a transaction on that connection.
3. Post a refund payload to the connection's webhook URL. See [refund made outside Gr4vy](https://integration.wpay.com.au/guides/features/simulators/webhooks.md#refund-made-outside-gr4vy).

Gr4vy records the refund on the transaction and sends a `refund.succeeded` webhook.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.