The Merchant Account Component gives the merchant everything they need to manage payouts in one place:

• Overview: The merchant's available balance and pending payments, and a summary of their account activity.
• Payout receivers: The merchant's payout receivers, where they can add, edit, and deactivate payout receivers.
• Payouts: The merchant's payouts, where they can schedule a new payout and view or cancel existing ones.

For how payouts work, see Payouts.

How to embed a Merchant Account Component

Session authentication

Create a session to grant the Merchant Account Component permissions to view and action the merchant's balance, payouts, and payout receivers.

Session contraints

The Merchant Account Component always shows a single merchant, so the session should be constrained to a specific merchant to ensure this session only has permissions to view the data associated to the merchant.

Session permission

The session should include at least the following permissions to view the merchant's account balance, payouts, and payout receivers:

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_account_component"
            ],
            "constraints": {
                "merchant": {
                    "merchant_id": "REPLACE_ME"
                }
            }
        }
    ]
}'

Each action the merchant can take requires its own permission group in the session, and the corresponding action in the component's allowed-actions prop.

Leave out the permission group for any action the merchant should not have. The following session gives the merchant every action:

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_account_component",
                "group#merchant_account_component.create_payout",
                "group#merchant_account_component.update_payout",
                "group#merchant_account_component.create_payout_receiver",
                "group#merchant_account_component.create_payout_method",
                "group#merchant_account_component.update_payout_receiver",
                "group#merchant_account_component.create_top_up"
            ],
            "constraints": {
                "merchant": {
                    "merchant_id": "REPLACE_ME"
                }
            }
        }
    ]
}'

JavaScript bundle

Include the merchant JavaScript bundle in your frontend to access the Merchant Account Component.

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

Content security policy (CSP)

🚧

Content Security Policy (CSP)

If your webpage uses a Content Security Policy to control what code is allowed on the page, you must make changes to allow the Rainforest Components to load.

You will need to update your Content Security Policy for script-src and frame-src directives to include:

*.rainforestpay.com

Merchant Account Component

Add the Rainforest Merchant Account Component with custom configuration designed in the component studio.

<rainforest-merchant-account
  session-key="REPLACE_ME"
  merchant-id="REPLACE_ME"
  tabs="overview,payout_receivers,payouts"
  allowed-actions="schedule-payout,cancel-payout,add-receiver,add-payout-method,edit-receiver,deactivate-receiver,add-funds"
></rainforest-merchant-account>

Customize the component

Head over to the Component Studio for more attributes you can provide to customize the component’s appearance and behavior.

UI customization

Customized UI can be integrated to the Merchant Account Component through the exposed slots.

Available slots

<rainforest-merchant-account>
    <div slot="details-loading-indicator">
        (your custom UI markup)
    </div>
</rainforest-merchant-account>

Prop configuration

Rainforest supports prop attributes to configure the Merchant Account Component with various functionality and styling. See the Component Studio for a full list of attributes and valid values.

Style

The component takes the same style-* attributes as all the other Rainforest components, such as style-accent-color, style-button-color, and style-font-family.

Tabs

The Merchant Account Component consists of three tabs:

• Overview: The merchant's available balance and pending payments, and a summary of their account activity.
• Payout receivers: The merchant's payout receivers, where they can add, edit, and deactivate payout receivers.
• Payouts: The merchant's payouts, where they can schedule a new payout and view or cancel existing ones.

Use the tabs prop to specify the tabs to display and their order. The first tab listed is the default displayed tab on render.

<rainforest-merchant-account
    tabs="overview,payouts,payout_receivers"
></rainforest-merchant-account>

Allowed actions

Use allowed-actions to choose which actions are available to the merchant, as a comma-separated list. Each action also needs its respective permission group in the session. Not specifying allowed-actions will embed the component in a read-only view.

<rainforest-merchant-account
    allowed-actions="add-funds,schedule-payout,cancel-payout,add-receiver,add-payout-method,edit-receiver,deactivate-receiver"
></rainforest-merchant-account>

Allowed actions:

Payout methods

Use allowed-payout-methods to choose how a bank account can be added to a payout receiver, as a comma-separated list. Not specifying allowed-payout-methods offers both.

• ACH - enter the account and routing numbers
• VALIDATED_ACH - authenticate into their online bank account through Rainforest's third-party partner, Plaid

Only the owner of the bank account can authenticate into it, so VALIDATED_ACH is only offered when the merchant adds a bank account to themselves as a payout receiver. For any other payout receiver, the merchant enters the account and routing numbers.

<rainforest-merchant-account
    allowed-payout-methods="ACH,VALIDATED_ACH"
></rainforest-merchant-account>

Column configuration

The Payouts Report and Payout Receivers Report will load with a set of default columns. Omit the payout-columns or payout-receiver-columns to use the defaults.

Default columns for the Payouts Report:

[
    {"name": "Payout ID", "type": "builtin", "value": "id"},
    {"name": "Created", "type": "builtin", "value": "created"},
    {"name": "Receiver", "type": "builtin", "value": "payout_receiver_name"},
    {"name": "Category", "type": "builtin", "value": "category"},
    {"name": "Status", "type": "builtin", "value": "status"},
    {"name": "Amount", "type": "builtin", "value": "amount"}
]

Default columns for the Payout Receivers Report:

[
    {"name": "Receiver", "type": "builtin", "value": "name"},
    {"name": "Type", "type": "builtin", "value": "type"},
    {"name": "Payout Method", "type": "builtin", "value": "payout_method"},
    {"name": "Status", "type": "builtin", "value": "status"},
    {"name": "Paid YTD", "type": "builtin", "value": "paid_ytd"}
]

Custom configuration

Columns can be customized to fit the needs of your platform. To override the default columns, pass the column specifications as a JSON payload in payout-columns or payout-receiver-columns.

<rainforest-merchant-account
    payout-columns='[{"name":"Scheduled date","type":"builtin","value":"scheduled_payout_date"}]'
    payout-receiver-columns='[{"name":"Receiver","type":"builtin","value":"name"}]'
></rainforest-merchant-account>

A column specification needs a name, type, and value.

• name: The display header for the column.
• type: Set to builtin or metadata.
• value: The key for the value to display. See the valid column values below.

Valid payout column values

Valid payout receiver column values

Metadata column

A column can display a custom metadata value set on the payout or payout receiver. The value for type metadata should be a valid JSONPath to the metadata key.

For example, a payout created with the following metadata:

{
    "invoice": {
        "id": "123",
        "vendor_email": "[email protected]"
    }
}

could have the following column specification to display the invoice ID:

{
    "name": "Invoice ID",
    "type": "metadata",
    "value": "$.invoice.id"
}

Templating columns

Specify a template to format the metadata for display. The pattern {{value}} is replaced with the value of the field. For example, this template displays the invoice ID as "Invoice #123":

{
    "name": "Invoice ID",
    "type": "metadata",
    "value": "$.invoice.id",
    "template": "Invoice #{{value}}"
}

Hyperlinks

The template can also be valid HTML to make a metadata column a hyperlink. For example, this template makes an email a mailto link:

{
    "name": "Vendor email",
    "type": "metadata",
    "value": "$.invoice.vendor_email",
    "template": "<a style=\"color:blue;text-decoration:underline;\" href=\"mailto:{{value}}\">{{value}}</a>"
}

Data filters

The Payouts and Payout receivers tabs can each be pre-loaded with a defined set of filters, including sort by and sort order. Data filters are defined by a JSON payload of key-value pairs passed into payout-data-filters or payout-receiver-data-filters. To pass multiple values for a key, define the value as an array.

Data filters are always applied to the respective report. Any filtering the merchant does in the component is in addition to the filters passed in.

Payouts report

A valid key for payout-data-filters includes any of the query params from the List payouts endpoint.

The Payouts report always filters to the merchant defined in the merchant-id prop of the Merchant Account Component, so payout-data-filters does not need a merchant_id.

Payout Receivers report

A valid key for payout-receiver-data-filters includes any of the query params from the List payout receivers endpoint.

Listen to webhooks

Subscribe to the following webhooks to keep your platform in sync:

• Payout webhooks - know when each payout is scheduled or canceled from the component.
• Payout receiver webhooks - know when each payout receiver is added, submitted, edited, or deactivated from the component.

Sandbox simulation

In the Sandbox environment, payments and payouts do not move on an automatic schedule, which allows you to have more control over testing.

To test the Merchant Account Component in Sandbox:

1. Activate the payout receiver. A third-party payout receiver added from the component stays Verifying in Sandbox after they are submitted. Move them to Active via the simulate payout receiver endpoint. A merchant paying themselves is already Active.
2. Make funds available. Simulate the merchant's payments completing via the simulate merchant complete payments endpoint. This transitions all the merchant's payments with the status of Processing to Succeeded, so the funds are in the merchant's available balance shown on the Overview tab.
3. Schedule the payout. Schedule the payout from the Payouts tab of the Merchant Account Component.
4. Simulate the payout status. Move the payout through its statuses via the simulate payout status endpoint: Processing, Succeeded, Failed with a failure code, Returned with an ACH return code, or Canceled. This allows you to test all webhooks for payouts that you will receive in Production.