Onboarding merchants

Overview

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.

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:

<rainforest-merchant-onboarding
    session-key="REPLACE_ME"
    merchant-id="REPLACE_ME"
    merchant-application-id="REPLACE_ME"
></rainforest-merchant-onboarding>

📘

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:

📘

Working with webhooks

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