Early Preview
This feature is currently in Beta. Please contact Rainforest support or your Platform Success Manager for more information on Payouts.

Webhooks can be configured to receive updates on every status change that occurs through the life cycle of a payout. For how to configure webhooks, see Webhooks.

Payout events

Events

It is recommended that your platform listen to the following Rainforest webhooks to notify your platform, the merchant, and the payout receiver on key events. Below is each webhook event and whether 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
Payout Receiver Notification - notify the payout receiver of the status of the payout

Webhook	Internal Notification	Merchant Notification	Payout Receiver Notification
`payout.scheduled`	❌	✅	❌
`payout.in_review`	✅	✅	❌
`payout.processing`	❌	❌	✅
`payout.succeeded`	❌	✅	❌
`payout.failed`	✅	✅	❌
`payout.returned`	✅	✅	✅
`payout.canceled`	❌	✅	❌

Payload

The webhook payload consists of:

data - represents all payout detail fields returned by the get payout endpoint
event_type - payout events denoted by the format of payout.{payout_status}

{
    "data": {
        "payout_id": "pyo_33F9AbCdEfGhIjKlMnOpQrStUvW",
        // ...
        "status": "PROCESSING",
        // ...
    },
    "event_type": "payout.processing"
}

Scheduled

Event: payout.scheduled

Triggered when a payout is created and scheduled to process on its scheduled payout date, or when a payout is approved after a risk review before its scheduled payout date.

Field	Description
`payout_id`	The unique payout identifier.
`payout_config_id`	The unique payout config identifier.
`merchant_id`	The unique merchant identifier.
`payout_receiver_id`	The unique payout receiver identifier.
`payment_method_id`	The unique payment method identifier of the payout receiver's bank account.
`category`	The payout category.
`idempotency_key`	A unique identifier provided by the platform.
`amount`	The amount of the payout, in minor units.
`currency_code`	Three-letter ISO currency code, in uppercase. Currently, only `USD` is supported.
`billing_fee`	The payout fee incurred for the payout, in minor units.
`status`	The status of the payout, will be `SCHEDULED`.
`requested_payout_date`	The date requested to process the payout.
`scheduled_payout_date`	The date the payout is scheduled to process.
`estimated_arrival_date`	The estimated date the funds will arrive in the payout receiver's bank account.
`metadata`	Valid JSON key-value object specified by the platform to store additional information on the payout.
`created_at`	Date and time payout was created at in UTC RFC 3339 format.
`scheduled_at`	Date and time payout was scheduled at in UTC RFC 3339 format.

In review

Event: payout.in_review

Triggered when a payout is flagged for risk review. See In review.

Field	Description
`payout_id`	The unique payout identifier.
`status`	The status of the payout, will be `IN_REVIEW`.
`updated_at`	Date and time payout was updated at in UTC RFC 3339 format.

Processing

Event: payout.processing

Triggered when a payout is processing and can no longer be edited or canceled.

Field	Description
`payout_id`	The unique payout identifier.
`status`	The status of the payout, will be `PROCESSING`.
`processed_at`	Date and time payout was processed at in UTC RFC 3339 format.
`updated_at`	Date and time payout was updated at in UTC RFC 3339 format.

Succeeded

Event: payout.succeeded

Triggered when a payout has completed processing and the funds were sent to the payout receiver.

Field	Description
`payout_id`	The unique payout identifier.
`status`	The status of the payout, will be `SUCCEEDED`.
`updated_at`	Date and time payout was updated at in UTC RFC 3339 format.

Failed

Event: payout.failed

Triggered when a payout could not be processed. The amount goes back to the merchant's available balance.

Field	Description
`payout_id`	The unique payout identifier.
`status`	The status of the payout, will be `FAILED`.
`failure_code`	The code explaining why the payout failed. See payout failure codes.
`failure_desc`	The description explaining why the payout failed.
`estimated_arrival_date`	Will be set to `null`.
`failed_at`	Date and time payout failed at in UTC RFC 3339 format.
`updated_at`	Date and time payout was updated at in UTC RFC 3339 format.

Returned

Event: payout.returned

Triggered when a payout is returned by the payout receiver's bank after it was processed. The amount goes back to the merchant's available balance.

Field	Description
`payout_id`	The unique payout identifier.
`status`	The status of the payout, will be `RETURNED`.
`return_code`	The ACH return code explaining why the payout was returned.
`return_desc`	The description of the ACH return code.
`estimated_arrival_date`	Will be set to `null`.
`returned_at`	Date and time payout was returned at in UTC RFC 3339 format.
`updated_at`	Date and time payout was updated at in UTC RFC 3339 format.

Canceled

Event: payout.canceled

Triggered when a payout is canceled before it was processed, by the merchant, the platform, or after a risk review. The amount goes back to the merchant's available balance.

Field	Description
`payout_id`	The unique payout identifier.
`status`	The status of the payout, will be `CANCELED`.
`cancel_reason`	The reason the payout was canceled, if provided.
`estimated_arrival_date`	Will be set to `null`.
`canceled_at`	Date and time payout was canceled at in UTC RFC 3339 format.
`updated_at`	Date and time payout was updated at in UTC RFC 3339 format.