Webhooks can be configured to receive updates on every status change that occurs through the life cycle of a deposit.

Deposit events

Events

It's recommended that your platform listen to the following Rainforest webhooks to notify your platform and the merchant on key events for deposits. 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
Email Merchant Notification - notify your merchants via an email
In Platform Merchant Notification - notify your merchants via an alert within your platform

Webhook	Internal Notification	Email Merchant Notification	In Platform Merchant Notification
deposit.scheduled	✅	❌	✅
deposit.processing	✅	❌	✅
deposit.succeeded	✅	✅	✅
deposit.failed	✅	✅	✅
deposit.canceled	✅	❌	✅

Payload

The webhook payload consists of:

data - represents all deposit fields returned by the get deposit endpoint
event_type - deposit events denoted by the format of deposit.{deposit_status}

{
    "data": {
        "deposit_id": "dep_2sOhrqqvczzMolLKkcWyWxquj0i",
        // ...
        "status": "PROCESSING",
        // ...
    },
    "event_type": "deposit.processing"
}

Scheduled

Event: deposit.scheduled

Triggered when an on-demand deposit is requested and scheduled. This is the first time your platform receives the deposit ID, amount, and scheduled deposit date. Funds have not been sent to the merchant's bank account.

Field	Description
`deposit_id`	The unique deposit identifier.
`merchant_id`	The unique merchant identifier.
`status`	The status of the deposit, will be `SCHEDULED`.
`amount`	The amount to be deposited, in minor units.
`is_on_demand`	Will be `true`.
`scheduled_deposit_date`	The date the deposit is scheduled to process on, in ISO 8601 format (YYYY-MM-DD).
`metadata`	The metadata provided when the on-demand deposit was requested.
`created_at`	Date and time deposit was created at in UTC RFC 3339 format.
`scheduled_at`	Date and time the deposit was scheduled at in UTC RFC 3339 format.

Processing

Event: deposit.processing

Triggered when a deposit is processing.

Field	Description
`deposit_id`	The unique deposit identifier.
`platform_id`	The unique platform identifier. Will be set if this deposit belongs to a platform.
`merchant_id`	The unique merchant identifier. Will be set if this deposit belongs to a merchant.
`status`	The status of the deposit, will be `PROCESSING`.
`amount`	The amount deposited, in minor units.
`deposit_type`	The types of of deposit. Valid values are `BILLING` or `FUNDING`. Billing only applies to merchants on gross billing.
`method_type`	The type of deposit method. Valid values are `ACH` or `PLAID_ACH`. Determines the `ach` or `plaid_ach` object is defined.
`ach`	ACH deposit method details, applicable if the `method_type` is `ACH`.
`plaid_ach`	ACH deposit method details from Plaid, applicable if the `method_type` is `PLAID_ACH`.
`created_at`	Date and time deposit was created at in UTC RFC 3339 format.
`processed_at`	Date and time deposit was processed at in UTC RFC 3339 format.

Succeeded

Event: deposit.succeeded

Triggered when a deposit has completed processing and the funds have been deposited into the merchant or platform's bank account.

Field	Description
`deposit_id`	The unique deposit identifier.
`status`	The status of the deposit, will be `SUCCEEDED`.

Failed

Event: deposit.failed

Triggered when a deposit unsuccessfully attempts to process. We attempted to deposit the funds to the merchant or platform's bank account, but the deposit was returned.

Field	Description
`deposit_id`	The unique deposit identifier.
`status`	The status of the deposit, will be `FAILED`.

Internal notification example

The following example is an internal notification to be sent your platform support team:

ystem Alert] T The below merchant deposit has failed to process. The Rainforest support team will reach out to resolve the issue to re-process the deposit. You are encouraged to notify the merchant of this and assist them with resolving the reason for the failed deposit.

Deposit ID: {insert deposit ID}

Merchant ID: {insert merchant ID}

Merchant Name: {insert merchant name}

External notification example

The following example is an external notification to be sent your merchant:

ystem Alert] T The PlatformPay team is reaching out to let you know that we recently attempted to deposit funds into your bank account. Unfortunately, this deposit attempt was returned by your bank. Do not worry, the reasons for these returned deposits can typically be resolved fairly quickly. Please contact us at {insert support contact} so that we can assist you with resolving the reason for this failed deposit.

Deposit ID: {insert deposit ID}

Deposit Amount: {insert deposit amount}

Canceled

Event: deposit.canceled

Triggered when an on-demand deposit is canceled before it processes. The funds return to the merchant's available balance and will be included in the merchant's next deposit.

Field	Description
`deposit_id`	The unique deposit identifier.
`status`	The status of the deposit, will be `CANCELED`.
`canceled_at`	Date and time the deposit was canceled at in UTC RFC 3339 format.
`canceled_by`	Who canceled the deposit. Valid values are `PLATFORM`, `MERCHANT`, or `RAINFOREST`.
`cancel_reason`	The reason the deposit was canceled, if one was provided.