--- updatedAt: 2025-09-08T21:27:04.000Z agentTools: projectIndex: https://docs.rainforestpay.com/llms.txt --- # Onboarding merchants via API Integrate with Rainforest's merchant onboarding endpoints to send merchant onboarding data via API > ❗️ This feature requires Rainforest approval > > If you're interested in onboarding your merchants with a direct to API integration, please reach out to your Customer Success Manager or [contact support](mailto:support@rainforestpay.com). Platforms that are approved by Rainforest can send sensitive merchant onboarding data, including bank accounts and Social Security Numbers, to Rainforest via a direct to API integration. Follow the steps below to onboard merchants via API: 1. Create a deposit method for your merchant's deposits 2. Create a merchant and merchant application 3. Update the merchant application with onboarding data, including the deposit method 4. Submit the merchant application for approval
# Create a deposit method *** Follow these steps to create a deposit method to later assign to the merchant application. This deposit method is where the merchant's funds for their payment activity will be deposited to. ## Create a deposit method config [Create deposit method config](https://docs.rainforestpay.com/reference/create_deposit_method_config) to set up a deposit method with information such as billing contact details before collecting the sensitive deposit method details (i.e the bank account number). ### Billing contact name The billing contact name should be set to the merchant's legal business name. All other billing contact are fields are optional. ## Create a deposit method Create a deposit via the [create deposit method](https://docs.rainforestpay.com/reference/create_deposit_method) endpoint with a valid request payload. Required fields are defined below. The Plaid ACH method type is not available in the direct to API integration. ### Request payload
Field Description Type Required
`deposit_method_config_id` The unique deposit method config identifier. Prefix is "cfg" in production and "sbx\_cfg" in sandbox. String ✔
`method_type` The type of deposit method. **Should be set to`ACH`.** String ✔
`ach` ACH payment method details. Required for method\_type `ACH`. ACH object ✔
`plaid_ach` Data to retrieve ACH account details from Plaid. *Plaid is not available in the direct to API integration.* Plaid ACH object ✘
`billing_contact` Billing contact details. Field `name` required. Billing contact object ✔
#### ACH | Field | Description | Type | Required | | :-------------------- | :------------------------------------------------------- | :----- | :------- | | `account_number` | The bank account number. | String | ✔ | | `routing_number` | The 9 digit routing number. | String | ✔ | | `account_type` | The account type. Defaulted to `CHECKING` if omitted. | String | ✘ | | `account_holder_type` | The account holder type. **Should be set to`BUSINESS`.** | String | ✔ | ## Save the deposit method ID Save the `deposit_method_id` to associate to the merchant's application in a following step.
# Create a merchant *** [Create the merchant](https://docs.rainforestpay.com/reference/create_merchant) and populate all necessary information. This will create the merchant and the initial merchant application. > 🚧 No free trial merchants > > It is **highly discouraged** to allow merchants who are on a trial or free software version of your platform to sign up for payments. Generally, merchants who are on a trial or free software version are not eligible for approval. Please reach out to your Platform Success Manager for more information. ## Requirements by merchant type Required fields for onboarding are dependent on the merchant type. See the following table for all fields that must be set in order to submit the merchant for approval. * ✅: required field * ❌: field cannot be set * ✚: optional field | Field | Individual | LLC | LLP | Partnership | Private Corporation | Public Corporation | Non-Profit Organization | Government | | :----------------------- | :--------- | :-- | :-- | :---------- | :------------------ | :----------------- | :---------------------- | :--------- | | `name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `dba_name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `legal_name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `merchant_type` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `mcc` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `email` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `website` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `phone_number` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `average_ticket` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `high_ticket` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `average_monthly_volume` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `address` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `tax_id` | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `owner_1` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `owner_2` | ❌ | ✚ | ✚ | ✚ | ❌ | ❌ | ❌ | ❌ | | `owner_3` | ❌ | ✚ | ✚ | ✚ | ❌ | ❌ | ❌ | ❌ | | `owner_4` | ❌ | ✚ | ✚ | ✚ | ❌ | ❌ | ❌ | ❌ | | `deposit_routes` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | #### Address fields | Field | Individual | LLC | LLP | Partnership | Private Corporation | Public Corporation | Non-Profit Organization | Government | | :--------------- | :--------- | :-- | :-- | :---------- | :------------------ | :----------------- | :---------------------- | :--------- | | `address_line_1` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `address_line_2` | ✚ | ✚ | ✚ | ✚ | ✚ | ✚ | ✚ | ✚ | | `city` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `state` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `postal_code` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `country` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | #### Owner fields | Field | Individual | LLC | LLP | Partnership | Private Corporation | Public Corporation | Non-Profit Organization | Government | | :--------------- | :--------- | :-- | :-- | :---------- | :------------------ | :----------------- | :---------------------- | :--------- | | `first_name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `last_name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `dob` | ✅ | ✅ | ✅ | ✅ | ✅ | ✚ | ✅ | ✚ | | `ssn` | ✅ | ✅ | ✅ | ✅ | ✅ | ✚ | ✅ | ✚ | | `email` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `phone_number` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `address_line_1` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `address_line_2` | ✚ | ✚ | ✚ | ✚ | ✚ | ✚ | ✚ | ✚ | | `city` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `state` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `postal_code` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `country` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | `ownership` | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ## Deposit routes The deposit route defines where the funds for the merchant's payments will be deposited to. Set the `deposit_routes` field to assign a deposit method to the merchant. For merchants on daily net billing, only the `PAYMENTS` deposit route needs to be set. ``` "deposit_routes": { "PAYMENTS": { "deposit_method_id": "{{deposit_method_id}}" } } ``` If your merchants are on [gross billing](https://docs.rainforestpay.com/docs/gross-billing), then you'll need to assign two deposit methods, one for `PAYMENTS` and one for `BILLING`: ``` "deposit_routes": { "PAYMENTS": { "deposit_method_id": "{{deposit_method_id}}" }, "BILLING": { "deposit_method_id": "{{deposit_method_id}}" } } ```
# Validate and update the merchant application *** ## Validation errors If the merchant application is missing required information, the [get merchant application](https://docs.rainforestpay.com/reference/get_merchant_application) will return the field `validation_errors` that will provide details on why the application cannot be submitted. ## Update the application After the merchant creation, [update the merchant application](https://docs.rainforestpay.com/reference/update_merchant_application) with any changes before submitting for approval.
# Submit the merchant application *** Once the application has been completed and all requirements have been met, [submit the merchant application](https://docs.rainforestpay.com/reference/submit_merchant_application) and provide validation that your merchant agreed to your Terms and Conditions. If there are validation errors on submission, the submission will not be allowed and the response will return the field `validation_errors`, similar to [get merchant application](https://docs.rainforestpay.com/reference/get_merchant_application).