A top-up adds funds from a bank account to a merchant’s available balance. This allows the merchant to send payouts for more than they have processed through payments with Rainforest.

Merchants top up their balance from within the Merchant Account Component.

Enable top-ups in the Merchant Account Component

Session permissions

Include the merchant_account_component.create_top_up permission group in the session for the Merchant Account Component, along with the merchant_account_component base group:

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

Allowed actions

Include add-funds in the component's allowed-actions to show the option to add funds:

<rainforest-merchant-account
    session-key="REPLACE_ME"
    merchant-id="REPLACE_ME"
    allowed-actions="add-funds"
></rainforest-merchant-account>

Top-up amount options

Use top-up-amount-options to set quick-select amounts the merchant can choose from. The value is a list of amounts in minor units. For example, 100000 is 1,000.00 USD. The merchant can still enter any other amount.

<rainforest-merchant-account
    allowed-actions="add-funds"
    top-up-amount-options="[100000, 500000, 1000000, 2500000]"
></rainforest-merchant-account>

When top-up-amount-options is not set, no quick-select amounts are shown and the merchant enters the amount.

Sandbox simulation

In the Sandbox environment, payments do not move on an automatic schedule. To make a top-up available in the merchant's balance, 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, including the top-up, to Succeeded.