Onboarding merchants

Onboarding merchants with Rainforest to process payments


Before they can process payments through your system, each merchant needs to be onboarded. Rainforest will need enough information about them so that we can complete a risk review, protecting your platform from potential bad actors.

The merchant onboarding process involves three steps:

  • Create the merchant in the Rainforest API
  • Embed Rainforest’s merchant onboarding component into your website so they can fill in the rest of their information.
  • Listen to webhooks to learn the result of our risk review.

Let’s get started!

Create the merchant

First, call the create merchant endpoint, providing as much information as you already have about the business.

Save the merchant_id and merchant_application_id from the response for future use. The merchant represents this business, while the application represents its information at one point in time. If the businesses moves to a new address, it will be the same merchant, but will now have a second application.

Embed the merchant onboarding component

The next step is to show Rainforest's merchant onboarding component to your merchants, so they can complete their business information and submit it for review.


Preview of the merchant onboarding component

You'll need to build a page on your website and get your merchants to visit it. You may want to add a notification icon or send an email — whatever you normally do when you need your customers to complete an action on your platform.

Session authentication

The page where you host the component should be secure and authenticated, so that you are sure the current user is authorized to view and edit this business's information.

Call the create session endpoint to authorize the current user to view and submit this application. The session for the merchant onboarding component should include at least the following statement:

curl --location 'https://api.rainforestpay.com/v1/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--data '{
    "ttl": 86400,
    "statements": [
            "permissions": ["group#merchant_onboarding_component"],
            "constraints": {
                "merchant": {
                    "merchant_id": "{{REPLACE_ME}}"
                "platform": {
                		"platform_id": "{{REPLACE_ME}}"

JavaScript bundle

Load the Rainforest merchant JavaScript bundle onto your page so that you can render our component:

<script type="module" src="https://static.rainforestpay.com/sandbox.merchant.js"></script>


Developing locally?

If you're testing your integration on an environment that does not use localhost as the origin, you will need to first configure your browser to allow Rainforest to use secure web APIs, like cryptography, which are normally disallowed over an insecure connection. See our instructions for more detail.

Then render the merchant onboarding component as HTML, providing the previously-created session_key, merchant_id, and merchant_application_id as attributes:



Customizing the component

See the merchant onboarding component studio for more attributes you can provide to customize the component's appearance and behavior.

Event listeners

Next, listen to the submitted event on the component to know that your user has completed and submitted the form. You can let them know that they are done on the current page or redirect them back to some other part of your website.

var component = document.querySelector('rainforest-merchant-onboarding');
component.addEventListener('submitted', function (data) {
    // Let the user know they are done, or redirect them elsewhere.

After the merchant submits the application in the component, the merchant's status will be ONBOARDING and the merchant's application status will be PROCESSING. In this state, Rainforest's systems are automatically reviewing the business information and the merchant cannot yet accept payments.


Testing in sandbox

If you're filling out the component in sandbox, you can use our test ACH accounts for the deposit payment method,

What happens next? In production, Rainforest will check the submitted application against our risk criteria and then asynchronously updates the status after a decision is made. In the sandbox environment, no actual risk review happens. To simulate the application being accepted, and advance the merchant so that they can take test payments, you can use the simulate API endpoint to simulate the merchant application being approved or rejected.

Listen to webhooks

Rainforest's risk review can take between an hour and two business days. Your system should subscribe to webhooks to find out the result.

When Rainforest has finished with the application review, the merchant application's status will update and you'll receive a corresponding webhook:

WebhookMerchant Application statusWhat it means and next steps
merchant_application.completedCOMPLETEDThis merchant's application has been approved.

You can let them know and start accepting payments for them.
merchant_application.needs_informationNEEDS_INFORMATIONDuring risk review, Rainforest identified a small inconsistency and needs the merchant to come back and provide clarification or fix a small typo.

You can either notify the merchant and re-render the component to them so that they can fill it out. Or your support team can contact them to collect the needed information manually and then enter it into the Rainforest Portal
merchant_application.in_reviewIN_REVIEWDuring risk review, Rainforest identified a major question about this merchant's application. We will contact you via a helpdesk ticket to clarify the situation. For now, you cannot accept payments via this merchant. (After Rainforest receives clarifying information, we may then update the application status to one of the other options in this table.)
merchant_application.declinedDECLINEDBased on the merchant's application, Rainforest is unable to process payments for them at this time.

Contact support if you have further questions about this merchant.


Working with webhooks

Read the webhooks overview for an introduction to configuring webhook listeners and validating webhook payloads.

What’s Next

Now that you have an onboarded merchant, you're ready to process payments: