Refund webhooks
Subscribe to refund webhooks for updates on status changes
Webhooks can be configured to receive updates on every status change that occurs through the life cycle of a refund.

Refund events
Events
It's recommended that your platform listen to the following Rainforest webhooks to notify your platform, the merchant, and the end user on key events. We'll break down each webhook event and if the following notifications should be sent:
- Internal Notification - notify your platform support team so they can assist your merchants
- Merchant Notification - notify your merchants via an email or alert within your platform
- End User (Payor) Notification - notify the end user (payor) of the result of the payin
Webhook | Internal Notification | Merchant Notification | End User (Payor) Notification |
---|---|---|---|
refund.created | ❌ | ❌ | ❌ |
refund.processing | ✅ | ✅ | ✅ |
refund.succeeded | ❌ | ❌ | ❌ |
refund.failed | ❌ | ❌ | ❌ |
refund.canceled | ❌ | ❌ | ✅ |
refund.in_review | ✅ | ✅ | ✅ |
Payload
The webhook payload consists of:
data
- represents all refund detail fields returned in the get payin endpointevent_type
- refund events denoted by the format ofrefund.{refund_status}
{
"data": {
"refund_id": "rfd_2sPMefai6yWsyp4MSGUkAo32pp7",
// ...
"status": "PROCESSING",
// ...
},
"event_type": "refund.processing"
}
Created
Event: refund.created
Triggered when a refund is created and waiting approval.
Field | Description |
---|---|
refund_id | The unique refund identifier. |
payin_id | The unique payin identifier to the associated payin that was refunded. |
merchant_id | The unique merchant identifier. |
idempotency_key | A unique identifier provided by the platform. |
amount | The amount of the refund to attempt to process, in minor units. |
currency_code | Three-letter ISO currency code, in uppercase. Currently, only USD is supported. |
reason | The reason a refund was issued. |
status | The status of the refund, will be CREATED . |
metadata | Valid JSON key-value object specified by the platform to store additional information on the refund. |
amount_splits | The amount splits of the payin, applicable if the payin config defined the amount splits. |
created_at | Date and time refund was created at in UTC RFC 3339 format. |
Processing
Event: refund.processing
Triggered when a refund is approved and is currently processing.
Field | Description |
---|---|
refund_id | The unique refund identifier. |
status | The status of the payin, will be PROCESSING . |
auth_code | The authorization code if the refund was approved. |
merchant_fees | The refund fee billed to the merchant. |
updated_at | Date and time refund was updated at in UTC RFC 3339 format. |
Succeeded
Event: refund.succeeded
Triggered when a refund has completed processing and is available for deposit.
Field | Description |
---|---|
refund_id | The unique refund identifier. |
status | The status of the payin, will be SUCCEEDED . |
updated_at | Date and time refund was updated at in UTC RFC 3339 format. |
Failed
Event: refund.failed
Triggered when a refund unsuccessfully attempted to process.
Field | Description |
---|---|
refund_id | The unique refund identifier. |
status | The status of the payin, will be FAILED . |
refusal_code | The code explaining the reason for the refusal if the payin or refund failed to process. |
refusal_desc | The description explaining the reason for the refusal if the payin or refund failed to process. This will be a human-readable value that may be presented to the end user. |
updated_at | Date and time refund was updated at in UTC RFC 3339 format. |
Canceled
Event: refund.canceled
Triggered when a refund is canceled before the refund completes processing.
Field | Description |
---|---|
refund_id | The unique refund identifier. |
status | The status of the payin, will be CANCELED . |
updated_at | Date and time refund was updated at in UTC RFC 3339 format. |
In review
Event: refund.in_review
Triggered when a refund is flagged for risk review and is not available for deposit.
Field | Description |
---|---|
refund_id | The unique refund identifier. |
status | The status of the payin, will be IN_REVIEW . |
updated_at | Date and time refund was updated at in UTC RFC 3339 format. |
Internal notification example
The following example is an internal notification to be sent your platform support team:
[System Alert] The below refund has moved to the status of In Review. This means the Rainforest risk team has flagged the refund for review and will be reaching out to the platform directly with the additional information required to complete the review.
Merchant ID: {insert merchant ID}
Merchant Name: {insert merchant name}
Refund ID: {insert refund ID}
External notification example
The following example is an external notification to be sent your merchant:
[System Alert] PlatformPay has flagged the below refund for further review. Do not worry this is common practice when processing payments. The PlatformPay team is simply attempting to understand the risk of processing this refund for your business. These reviews typically only take a couple of days to complete. Once we complete our review we will release the refund for deposit. The PlatformPay team will reach out directly with information on how to get your funds released.
Don’t worry your funds are safe and this is a standard part of payment processing that ensures the security and safety of your funds and protects your business against potential bad actors.
Refund ID: {insert refund ID}
Updated 10 days ago