Skip to main content
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.
  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. 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.

​
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. The transaction’s history in the dashboard and in list transaction events 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.
Gr4vy records the refund on the transaction and sends a refund.succeeded webhook.