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	❌	❌	❌

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.