Merchant application webhooks
Subscribe to merchant application webhooks for updated on status changes
Webhooks can be configured to receive updates on every status change that occurs through the life cycle of a merchant application.

Merchant application 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_application.created | ❌ | ✅ | ✅ |
merchant_application.in_progress | ❌ | ❌ | ✅ |
merchant_application.processing | ❌ | ✅ | ✅ |
merchant_application.needs_information | ✅ | ✅ | ✅ |
merchant_application.in_review | ✅ | ✅ | ✅ |
merchant_application.completed | ✅ | ✅ | ✅ |
merchant_application.declined | ✅ | ✅ | ✅ |
Payload
The webhook payload consists of:
data
- represents all merchant application fields returned by the get merchant application endpointevent_type
- merchant application events denoted by the format ofmerchant_application.{merchant_application_status}
{
"data": {
"merchant_application_id": "app_2sOuOghBfy4SGFS6b7Le8uW8zGo",
"merchant_id": "mid_2sOuQknV0ornUMNElq9HS3Y5XUv",
// ...
"status": "CREATED",
// ...
},
"event_type": "merchant_application.created"
}
Created
Event: merchant_application.created
Triggered when a merchant application is created. A merchant's initial merchant application is created when the merchant is created. The application has not been updated by the merchant yet.
Field | Description |
---|---|
merchant_application_id | The unique merchant application identifier. |
merchant_id | The unique merchant identifier to the associated merchant. |
status | The status of the merchant application, will be CREATED . |
created_at | Date and time merchant application was created at in UTC RFC 3339 format. |
In progress
Event: merchant_application.in_progress
Triggered when a merchant application is updated for the first time indicating that the application is being filled out.
Field | Description |
---|---|
merchant_application_id | The unique merchant application identifier. |
merchant_id | The unique merchant identifier to the associated merchant. |
status | The status of the merchant application, will be IN_PROGRESS . |
updated_at | Date and time merchant application was last updated at in UTC RFC 3339 format. |
Processing
Event: merchant_application.processing
Triggered when a merchant application is submitted and the application is in the process of underwriting and onboarding.
Field | Description |
---|---|
merchant_application_id | The unique merchant application identifier. |
merchant_id | The unique merchant identifier to the associated merchant. |
status | The status of the merchant application, will be PROCESSING . |
submitted_at | Date and time merchant application was submitted at for approval in UTC RFC 3339 format. |
Needs information
Event: merchant_application.needs_information
Triggered when a merchant application could not be approved and requires additional verification for onboarding. See the Additional verification for merchant onboarding guide for how to collect the needed information from the merchant.
Field | Description |
---|---|
merchant_application_id | The unique merchant application identifier. |
merchant_id | The unique merchant identifier to the associated merchant. |
status | The status of the merchant application, will be NEEDS_INFORMATION . |
updated_at | Date and time merchant application 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 application has entered the status of Needs Information. This means Rainforest needs additional documentation in order to approve the merchant application. Please access the merchant application or login to the Rainforest Portal to review the information needed. We recommend reaching out to the merchant directly to notify them of the information needed to complete the review of their merchant application.
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] Your application for PlatformPay needs a bit more information to get across the finish line. Do not worry as this is a normal step in the process. Please click the link below to provide the required information.
{include link back to merchant application}
Note: Once the additional information is submitted, we will review your application within 2 business days.
In review
Event: merchant_application.in_review
Triggered when a merchant application could not be approved and requires additional verification for onboarding that cannot be resolved with the Needs Information onboarding flow. We will contact the platform via the underwriting email provided by the platform for next steps.
Field | Description |
---|---|
merchant_application_id | The unique merchant application identifier. |
merchant_id | The unique merchant identifier to the associated merchant. |
status | The status of the merchant application, will be IN_REVIEW . |
in_review_at | Date and time merchant application was moved to in review 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 application has entered the status of In Review. This means Rainforest needs additional documentation in order to approve the merchant application. Rainforest will be sending clarification to the platform on the additional information needed to approve the account to the email provided to Rainforest. Please work with the merchant to resolve the requested information/clarification.
Merchant ID: {insert merchant ID}
Merchant Name: {insert merchant name}
Completed
Event: merchant_application.completed
Triggered when a merchant application is approved and the merchant is now active. The merchant's information in the application will not be updated once application is completed. All fields on the merchant application are now represented on the merchant.
Field | Description |
---|---|
merchant_application_id | The unique merchant application identifier. |
merchant_id | The unique merchant identifier to the associated merchant. |
status | The status of the merchant application, will be COMPLETED . |
approved_at | Date and time merchant application was approved in UTC RFC 3339 format. |
Declined
Event: merchant_application.declined
Triggered when a merchant application is declined for a specific reason. This is a final decision and the application cannot be re-opened.
Field | Description |
---|---|
merchant_application_id | The unique merchant application identifier. |
merchant_id | The unique merchant identifier to the associated merchant. |
status | The status of the merchant application, will be DECLIINED . |
declined_at | Date and time merchant application was declined in UTC RFC 3339 format. |
Updated 10 days ago