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 statuses

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
WebhookInternal NotificationEmail Merchant NotificationIn 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 endpoint
  • event_type - merchant application events denoted by the format of merchant_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.

FieldDescription
merchant_application_idThe unique merchant application identifier.
merchant_idThe unique merchant identifier to the associated merchant.
statusThe status of the merchant application, will be CREATED.
created_atDate 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.

FieldDescription
merchant_application_idThe unique merchant application identifier.
merchant_idThe unique merchant identifier to the associated merchant.
statusThe status of the merchant application, will be IN_PROGRESS.
updated_atDate 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.

FieldDescription
merchant_application_idThe unique merchant application identifier.
merchant_idThe unique merchant identifier to the associated merchant.
statusThe status of the merchant application, will be PROCESSING.
submitted_atDate 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.

FieldDescription
merchant_application_idThe unique merchant application identifier.
merchant_idThe unique merchant identifier to the associated merchant.
statusThe status of the merchant application, will be NEEDS_INFORMATION.
updated_atDate 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.

FieldDescription
merchant_application_idThe unique merchant application identifier.
merchant_idThe unique merchant identifier to the associated merchant.
statusThe status of the merchant application, will be IN_REVIEW.
in_review_atDate 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.

FieldDescription
merchant_application_idThe unique merchant application identifier.
merchant_idThe unique merchant identifier to the associated merchant.
statusThe status of the merchant application, will be COMPLETED.
approved_atDate 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.

FieldDescription
merchant_application_idThe unique merchant application identifier.
merchant_idThe unique merchant identifier to the associated merchant.
statusThe status of the merchant application, will be DECLIINED.
declined_atDate and time merchant application was declined in UTC RFC 3339 format.