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

Merchant events

Events

It's recommended that your platform listen to the following Rainforest webhooks to notify your platform and your merchants 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
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
merchant.pending	❌	❌	❌
merchant.onboarding	❌	❌	❌
merchant.active	❌	❌	❌
merchant.suspended	✅	✅	✅
merchant.deactivated	✅	✅	✅
merchant.canceled	❌	❌	❌
merchant.deposit_routes_updates	❌	✅	✅
merchant.funding_deposit_disabled	✅	✅	✅
merchant.funding_deposit_enabled	❌	✅	✅
merchant.billing_deposit_disabled	✅	✅	✅
merchant.billing_deposit_enabled	❌	✅	✅
merchant.accelerated_ach_updated	✅	❌	❌

Payload

The webhook payload consists of:

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

{
    "data": {
        "merchant_id": "chb_2sOgSgPTWQ8tuxhSn0DeIdLDUjm",
        // ...
        "status": "ACTIVE",
        // ...
    },
    "event_type": "merchant.active"
}

Pending

Event: merchant.pending

Triggered when a merchant and the initial merchant application is created.

Field	Description
`merchant_id`	The unique merchant identifier.
`status`	The status of the merchant, will be `PENDING`.
`latest_merchant_application`	The initial merchant application created associated to the merchant.
`created_at`	Date and time merchant was created at in UTC RFC 3339 format.

Onboarding

Event: merchant.onboarding

Triggered when a merchant's initial application is submitted and the merchant is in the process of underwriting and onboarding.

Field	Description
`merchant_id`	The unique merchant identifier.
`status`	The status of the merchant, will be `ONBOARDING`.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.

Active

Event: merchant.active

Triggered when a merchant is successfully onboarded and the merchant is ready to process payments.

Field	Description
`merchant_id`	The unique merchant identifier.
`billing_profile_id`	The unique billing profile identifier. Defines the fees applies when processing payments and deposits.
`billing_frequency`	The merchant billing frequency. Valid values are `DAILY` or `MONTHYL`.
`billing_type`	The merchant billing type. Valid values are `NET` or `GROSS`.
`deposit_frequency`	The merchant auto-deposit frequency. Valid values are `DAILY` or `DISABLED`.
`card_release_delay_days`	The number of days after settlement until card-processed funds are available for deposit.
`ach_release_delay_days`	The number of days after settlement until ACH-processed funds are available for deposit.
`status`	The status of the merchant, will be `ACTIVE`.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.

Suspended

Event: merchant.suspended

Triggered when a merchant is suspended and the merchant cannot process payments or receive deposits.

Field	Description
`merchant_id`	The unique merchant identifier.
`status`	The status of the merchant, will be `SUSPENDED`.
`updated_at`	Date and time merchant was last 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 merchant account has entered the status of Suspended. At this time, the merchant is unable to process payments or receive deposits. The Rainforest risk team will be reaching out directly with clarification on the information required to move the merchant back to Active and enable processing again.

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:

[System Alert] We regret to inform you that your merchant account for payment processing has been temporarily suspended. We sincerely apologize for this inconvenience. The PlatformPay team would love to assist you with resolving this matter as quickly as possible so that payment processing functionality can be restored. Please contact {support email} so that we can assist you with resolving this matter.

Deactivated

Event: merchant.deactivated

Triggered when a merchant is deactivated. The merchant cannot process payments, but can receive deposits for any outstanding funds.

Field	Description
`merchant_id`	The unique merchant identifier.
`status`	The status of the merchant, will be `DEACTIVATED`.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.

Canceled

Event: merchant.canceled

Triggered when a merchant is canceled prior to being activated.

Field	Description
`merchant_id`	The unique merchant identifier.
`status`	The status of the merchant, will be `CANCELED`.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.

Deposit routes updated

Event: merchant.deposit_routes_updated

Triggered when a merchant's deposit route is updated, indicating that the merchant's deposit method has been updated.

Field	Description
`merchant_id`	The unique merchant identifier.
`deposit_routes`	The deposit routes defining where the funds for the merchant's payments will be deposited to. For merchants on net billing, only the `PAYMENTS` deposit route will be set. For merchants on gross billing, the `BILLING` deposit route will also be set.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.

Funding deposit disabled

Event: merchant.funding_deposit_disabled

Triggered when a merchant's funding deposits are disabled. The merchant will not receive funds for their payments.

Field	Description
`merchant_id`	The unique merchant identifier.
`funding_deposits_enabled`	Boolean indicating if funding deposits are enabled. The funding deposit consists of the payment activity volume.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.

Funding deposit enabled

Event: merchant.funding_deposit_enabled

Triggered when a merchant's funding deposits are enabled. The merchant will receive funds for their payments on the next available funding date, respective of the merchant's funding deposit frequency.

Field	Description
`merchant_id`	The unique merchant identifier.
`funding_deposits_enabled`	Boolean indicating if funding deposits are enabled. The funding deposit consists of the payment activity volume.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.

Billing deposit disabled

Event: merchant.billing_deposit_disabled

Triggered when a merchant's billing deposits are disabled. Only applicable for merchants on gross billing.

Field	Description
`merchant_id`	The unique merchant identifier.
`billing_deposits_enabled`	Boolean indicating if billing deposits are enabled. The billing deposit consists of the billing fees for each payment activity.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.

Billing deposit enabled

Event: merchant.billing_deposit_enabled

Triggered when a merchant's billing deposits are enabled. Only applicable to merchants on gross billing.

Field	Description
`merchant_id`	The unique merchant identifier.
`billing_deposits_enabled`	Boolean indicating if billing deposits are enabled. The billing deposit consists of the billing fees for each payment activity.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.

Accelerated ACH updated

Event: merchant.accelerated_ach_updated

Triggered when a merchant's accelerated ACH mode is updated. Rainforest can disable this feature and set the mode to DISABLED_BY_RAINFOREST.

Field	Description
`merchant_id`	The unique merchant identifier.
`accelerated_ach_mode`	Determines if an ACH payin will utilize the Accelerated ACH Release Delay Days when the payin meets the criteria. Value can be `ENABLED`, `DISABLED`, and `DISABLED_BY_RAINFOREST`.
`updated_at`	Date and time merchant was last updated at in UTC RFC 3339 format.