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 receiver. For how to configure webhooks, see Webhooks.

Payout receiver 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 their onboarding

Webhook	Internal Notification	Merchant Notification	Payout Receiver Notification
`payout_receiver.needs_information`	❌	❌	❌
`payout_receiver.verifying`	❌	❌	❌
`payout_receiver.needs_method`	✅	✅	✅
`payout_receiver.active`	❌	✅	✅
`payout_receiver.declined`	✅	✅	❌
`payout_receiver.deactivated`	❌	✅	❌

Payload

The webhook payload consists of:

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

{
    "data": {
        "payout_receiver_id": "rcv_2A4d6U0tMyovzTbVT1ktmRzdRaD",
        // ...
        "status": "ACTIVE",
        // ...
    },
    "event_type": "payout_receiver.active"
}

Needs information

Event: payout_receiver.needs_information

Triggered when a payout receiver is created and their details are being collected before they can be submitted for verification.

Field	Description
`payout_receiver_id`	The unique payout receiver identifier.
`merchant_id`	The unique merchant identifier.
`type`	The type of payout receiver. Valid values are `MERCHANT`, `EXTERNAL_BUSINESS`, and `EXTERNAL_INDIVIDUAL`.
`name`	The friendly name the merchant uses for the payout receiver.
`legal_name`	The legal registered name, applicable if the type is `EXTERNAL_BUSINESS`.
`first_name`	The first name, applicable if the type is `EXTERNAL_INDIVIDUAL`.
`last_name`	The last name, applicable if the type is `EXTERNAL_INDIVIDUAL`.
`default_payout_category`	The category used on payouts to the payout receiver when a payout does not set one.
`status`	The status of the payout receiver, will be `NEEDS_INFORMATION`.
`payout_receiver_payment_methods`	The payout receiver's bank accounts.
`metadata`	Valid JSON key-value object specified by the platform to store additional information on the payout receiver.
`created_at`	Date and time payout receiver was created at in UTC RFC 3339 format.

Verifying

Event: payout_receiver.verifying

Triggered when a payout receiver is submitted and Rainforest is verifying them and their bank accounts.

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

Needs method

Event: payout_receiver.needs_method

Triggered when a payout receiver does not have an active bank account, either after verification or after their last active bank account is deactivated because a payout was returned. A bank account must be added and verified before the payout receiver can be paid.

Field	Description
`payout_receiver_id`	The unique payout receiver identifier.
`status`	The status of the payout receiver, will be `NEEDS_METHOD`.
`payout_receiver_payment_methods`	The payout receiver's bank accounts, none of which are active.
`updated_at`	Date and time payout receiver was updated at in UTC RFC 3339 format.

Active

Event: payout_receiver.active

Triggered when a payout receiver is verified and has an active bank account, so they can be paid.

Field	Description
`payout_receiver_id`	The unique payout receiver identifier.
`status`	The status of the payout receiver, will be `ACTIVE`.
`payout_receiver_payment_methods`	The payout receiver's bank accounts, including their default.
`payout_receiver_payment_methods.is_default`	Whether the payment method is the payout receiver's default for payouts. When the payout receiver becomes `ACTIVE`, their first verified bank account is set as the default.
`updated_at`	Date and time payout receiver was updated at in UTC RFC 3339 format.

Declined

Event: payout_receiver.declined

Triggered when a payout receiver does not pass verification and cannot be paid.

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

Deactivated

Event: payout_receiver.deactivated

Triggered when a payout receiver is deactivated and can no longer be paid. A deactivated payout receiver cannot be reactivated.

Field	Description
`payout_receiver_id`	The unique payout receiver identifier.
`status`	The status of the payout receiver, will be `DEACTIVATED`.
`deactivated_by`	Who deactivated the payout receiver. Valid values are `MERCHANT`, `PLATFORM`, and `RAINFOREST`.
`updated_at`	Date and time payout receiver was updated at in UTC RFC 3339 format.