Rainforest Merchant Applications API
Resources for merchant application functions.
OpenAPI Specification
openapi: 3.1.0
info:
title: Authentication ACH Returns Merchant Applications API
version: 1.0.0
description: This resource is used for authentication actions
contact:
name: Rainforest
email: support@rainforestpay.com
url: https://rainforestpay.com
servers:
- url: https://api.sandbox.rainforestpay.com
description: Sandbox server
- url: https://api.rainforestpay.com
description: Production server
security:
- BearerAuth: []
tags:
- name: Merchant Applications
description: Resources for merchant application functions.
paths:
/v1/merchants/{merchant_id}/applications:
get:
operationId: list_merchant_applications
summary: List merchant applications
description: 'Query a list of a merchant''s applications with optional search criteria.
Note that the `data` object is structured to reserve future support for pagination.
However, pagination of merchant applications is not supported at this time.'
parameters:
- $ref: '#/paths/~1v1~1merchants/get/parameters/0'
- $ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D/get/parameters/1'
in: path
- name: status
in: query
description: 'One or more merchant application statuses to filter by. Provide parameter multiple times to filter by multiple payment status types.
`COMPLETED` `CREATED` `DECLINED` `IN_REVIEW` `IN_PROGRESS` `NEEDS_INFORMATION` `PROCESSING`'
schema:
type: array
items:
$ref: '#/paths/~1v1~1merchants/get/parameters/10/schema/items'
- $ref: '#/paths/~1v1~1merchants/get/parameters/8'
in: query
- $ref: '#/paths/~1v1~1merchants/get/parameters/9'
in: query
- name: sort_by
in: query
description: Optional value by which to sort the result set. Default sort by is created_at.
schema:
type: string
enum:
- created_at
- updated_at
- status
- $ref: '#/paths/~1v1~1merchants/get/parameters/14'
in: query
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
status:
$ref: '#/paths/~1v1~1merchants/get/responses/200/content/application~1json/schema/properties/status'
data:
allOf:
- $ref: '#/paths/~1v1~1merchants/get/responses/200/content/application~1json/schema/properties/data/allOf/0'
- type: object
properties:
results:
description: List of merchant's applications.
type: array
items:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D~1simulate/post/responses/200/content/application~1json/schema/properties/data'
errors:
$ref: '#/paths/~1v1~1merchants/get/responses/200/content/application~1json/schema/properties/errors'
'400':
$ref: '#/paths/~1v1~1merchants/get/responses/400'
'401':
$ref: '#/paths/~1v1~1merchants/get/responses/401'
'403':
$ref: '#/paths/~1v1~1merchants/get/responses/403'
'404':
$ref: '#/paths/~1v1~1merchants/get/responses/404'
5XX:
$ref: '#/paths/~1v1~1merchants/get/responses/5XX'
tags:
- Merchant Applications
/v1/merchants/{merchant_id}/applications/{merchant_application_id}:
get:
operationId: get_merchant_application
summary: Get merchant application
description: Get merchant application details by the merchant application ID.
parameters:
- $ref: '#/paths/~1v1~1merchants/get/parameters/0'
- $ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D/get/parameters/1'
in: path
- in: path
required: true
name: merchant_application_id
schema:
type: string
description: "The unique merchant application identifier. \n\nPrefix is \"app\" in production and \"sbx_app\" in sandbox."
examples:
production:
value: app_2K60sPyXceGssCVOkKFMS1gommb
sandbox:
value: sbx_app_2K60sPyXceGssCVOkKFMS1gommb
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
status:
$ref: '#/paths/~1v1~1merchants/get/responses/200/content/application~1json/schema/properties/status'
data:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema'
errors:
$ref: '#/paths/~1v1~1merchants/get/responses/200/content/application~1json/schema/properties/errors'
'400':
$ref: '#/paths/~1v1~1merchants/get/responses/400'
'401':
$ref: '#/paths/~1v1~1merchants/get/responses/401'
'403':
$ref: '#/paths/~1v1~1merchants/get/responses/403'
'404':
$ref: '#/paths/~1v1~1merchants/get/responses/404'
5XX:
$ref: '#/paths/~1v1~1merchants/get/responses/5XX'
tags:
- Merchant Applications
patch:
operationId: update_merchant_application
summary: Update merchant application
description: Update a merchant application. Only fields included in the payload will be updated. Omitted fields will not be updated. To remove a field, set the value to `null`.
parameters:
- $ref: '#/paths/~1v1~1merchants/get/parameters/0'
- $ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D/get/parameters/1'
in: path
- $ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/get/parameters/2'
in: path
requestBody:
content:
application/json:
schema:
description: The merchant application. Applications are used for initial approval of a merchant and for updates to an existing merchant that must be re-approved.
type: object
properties:
merchant_application_id:
$ref: '#/paths/~1v1~1merchants/post/responses/200/content/application~1json/schema/properties/data/properties/merchant_application_id'
readOnly: true
merchant_id:
$ref: '#/paths/~1v1~1merchants/post/responses/200/content/application~1json/schema/properties/data/properties/merchant_id'
readOnly: true
platform_id:
$ref: '#/paths/~1v1~1billing_profiles/post/requestBody/content/application~1json/schema/allOf/0/properties/platform_id'
readOnly: true
billing_profile_id:
readOnly: true
description: "The unique billing profile identifier. \n\nPrefix is \"bpf\" in production and \"sbx_bpf\" in sandbox."
type: string
example: bpf_2DrDFJPutxE5AIbJSopAnqniEbr
name:
description: The unique identifier for the merchant business name.
type: string
example: Merchant
maxLength: 100
dba_name:
description: The merchant’s public-facing name. This may be the same as the legal name if the merchant does not operate under a different name.
type: string
example: Merchant
maxLength: 100
legal_name:
description: The merchant legal registered business name.
type: string
example: Merchant, Inc.
maxLength: 100
merchant_type:
description: The merchant's type of business.
type: string
enum:
- INDIVIDUAL
- LLC
- LLP
- PARTNERSHIP
- PRIVATE_CORPORATION
- PUBLIC_CORPORATION
- NON_PROFIT_ORG
- GOVERNMENT
mcc:
description: The merchant category code.
type: string
example: 4722
maxLength: 4
minLength: 1
mcc_desc:
readOnly: true
description: The merchant category code description.
type: string
example: Travel Agencies and Tour Operators
email:
description: The merchant business email.
type: string
example: merchant@example.com
website:
description: The merchant website. Must begin with http:// or https://
type: string
example: https://www.merchantwebsite.com
maxLength: 100
minLength: 1
website_validation_disabled:
description: Boolean indicating if website validation should be disabled.
type: bool
phone_number:
description: The merchant phone number, including extension.
type: string
example: '+14041234567'
maxLength: 100
minLength: 1
average_ticket:
description: 'The merchant average ticket amount, in USD minor units.
For example, 1000 is 10.00 USD.'
type: integer
example: 1000
minimum: 1
high_ticket:
description: 'The merchant high ticket amount, in USD minor units.
For example, 1000 is 10.00 USD.'
type: integer
example: 1000
minimum: 1
average_monthly_volume:
description: 'The merchant average monthly volume amount, in USD minor units.
For example, 1000 is 10.00 USD.'
type: integer
example: 1000
minimum: 1
address:
type: object
properties:
address_line_1:
description: First line of street address.
type: string
example: 123 Example Street
maxLength: 100
address_line_2:
description: Second line of street address, if required.
type: string
example: Suite 123
maxLength: 100
city:
description: City for address.
type: string
example: Atlanta
maxLength: 100
state:
description: State, province, or region for address.
type: string
example: GA
maxLength: 100
postal_code:
description: Postal code or ZIP code for address.
type: string
example: '30305'
maxLength: 15
country:
description: "2-digit country code. \nFind country codes here: https://www.iso.org/obp"
type: string
example: US
maxLength: 2
minLength: 2
encrypted_tax_id:
writeOnly: true
description: The merchant tax ID, encrypted with RSA-OAEP-SHA256. Required for all merchant types except for INDIVIDUAL.
type: string
example: SUPywcKsExepLYVgbqfHtOXc2NNM8LOTvsACcR5jkKaGr0lMRY/Lf5xflVXAl/9vuNWEnDy/jh7oDC9uH2j3+ha0uUPBSXz09FSSZ4Y2d71zBze6m+xKXJWTvX53dBZjpp6amuW7GnJNw6UAFEjjTe8Z4rm03T9IRd2VOdkyWl5fNTZyC7hXQpvfO/TjzzBc5T2N5k7KmnQovdQovGQhh4niKHIQntmM6lKyXWrFGlY9Erto30rJLJgR2BHhvEVnFo4EQ/pDWqLwjmqTErmDu4nGtNgpOJMBwQ7xl1Y+vLlT8ZzvPJebzntM/6r9f5TiHCty4Age3M7P6Cu0/Anmg7LrLP19lZf9n0j4cdXPl0sb1l7tjjnlcBUS7wPdrHl+tXGfOojGPB4tXgDzS6qY+cvns+ybEK/T3HU8tCUiPXgN6IpZ2b0GEpfh6BvG+q1Hov68UOkeUmF3keeKMuk1PLL5FcveXSifRnn+fyuAP4D4pBw8itMXsJ5SfkaLOuSXm95m+CP4vOUDAlkG0t0RJckSmG+Ttq2Lu9ZOREWkwDNZ2WyJtvlGa5mOPl7Vlf65U3LJYsZLEzNaeZoV1M6fp3RHZ3t6M3uXmpHDgsHwMSL8z9/ICwpXhBtj7PDeiOv34+dgF5YbLGaHtTkzUPsK8tadzAEyl5yhvVnJ26+Ysho=
tax_id_last_4:
description: The last 4 digits of the merchant tax ID. Required for all merchant types except for INDIVIDUAL.
type: string
example: '6789'
maxLength: 4
minLength: 4
no_owner_has_25_percent:
type: boolean
nullable: true
description: Indicates that no owner holds 25% or more ownership of the merchant. When set to `true`, owner ownership percentages are not required to be 25% or greater.
owner_1:
type: object
properties:
first_name:
description: First name of the owner.
type: string
example: Jane
maxLength: 100
minLength: 1
last_name:
description: Last name of the owner.
type: string
example: Smith
maxLength: 100
minLength: 1
dob:
description: Date of birth of the owner, in ISO 8601 format (YYYY-MM-DD)
type: string
example: '1990-10-10'
ssn:
writeOnly: true
description: 'The Social Security Number of the owner, formatted with no spaces (e.g. 987654321).
Setting this field requires Rainforest approval. Platforms that meet all [requirements](doc:send-sensitive-data-via-api#requirements) and are approved by Rainforest can send the Social Security Number to Rainforest via a direct API integration.'
type: string
example: '987654321'
ssn_last_4:
readOnly: true
description: Last 4 digits of the Social Security Number
type: string
example: '4321'
maxLength: 4
minLength: 4
email:
description: Email of the owner.
type: string
example: owner@example.com
maxLength: 100
minLength: 1
phone_number:
description: Phone number of the owner, including extension.
type: string
example: '+12342342345'
maxLength: 100
minLength: 1
address_line_1:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/address/properties/address_line_1'
address_line_2:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/address/properties/address_line_2'
city:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/address/properties/city'
state:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/address/properties/state'
postal_code:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/address/properties/postal_code'
country:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/address/properties/country'
ownership:
description: The percentage of ownership of the merchant. Required for LLC, LLP, and PARTNERSHIP merchant types.
type: number
maximum: 100
minimum: 25
owner_2:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/owner_1'
owner_3:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/owner_1'
owner_4:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/owner_1'
billing_frequency:
$ref: '#/paths/~1v1~1merchants/post/requestBody/content/application~1json/schema/allOf/0/properties/billing_frequency'
readOnly: true
billing_type:
$ref: '#/paths/~1v1~1merchants/post/requestBody/content/application~1json/schema/allOf/0/properties/billing_type'
readOnly: true
deposit_frequency:
$ref: '#/paths/~1v1~1merchants/post/requestBody/content/application~1json/schema/allOf/0/properties/deposit_frequency'
readOnly: true
card_release_delay_days:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D/patch/requestBody/content/application~1json/schema/properties/card_release_delay_days'
readOnly: true
ach_release_delay_days:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D/patch/requestBody/content/application~1json/schema/properties/ach_release_delay_days'
readOnly: true
validated_ach_release_delay_days:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D/patch/requestBody/content/application~1json/schema/properties/validated_ach_release_delay_days'
readOnly: true
balance_checked_ach_release_delay_days:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D/patch/requestBody/content/application~1json/schema/properties/balance_checked_ach_release_delay_days'
readOnly: true
allowed_payment_method_types:
readOnly: true
description: The allowed payment method types available for processing.
type: array
items:
type: string
enum:
- VISA_CREDIT
- VISA_DEBIT
- MASTERCARD_CREDIT
- MASTERCARD_DEBIT
- DISCOVER_CREDIT
- DISCOVER_DEBIT
- AMERICAN_EXPRESS_CREDIT
- AMERICAN_EXPRESS_DEBIT
- ACH_DEBIT
- PLAID_ACH_DEBIT
deposit_routes:
type: object
description: 'Object with key names that correspond to the purpose of deposit method.
For example, the deposit route for the PAYMENTS key represents the deposit method being used for the merchant''s funding deposits. The deposit route for the BILLING key represents the deposit method being used for the merchant''s billing deposits, only applicable for merchants on gross billing.'
additionalProperties:
type: object
properties:
deposit_method_id:
description: 'The unique deposit method identifier to use for this deposit route.
Prefix is "dmt" in production and "sbx_dmt" in sandbox.'
type: string
nullable: true
example: dmt_2DrDRpyAdp5MPUJnrJmoZcMmtfF
description:
type: string
readOnly: true
description: 'The description text to display in the merchant onboarding component when prompting the merchant to input the deposit method details.
This value is read-only and set by Rainforest at this time.'
allow_merchant_to_update:
type: boolean
readOnly: true
description: 'Indicates if the deposit method can be updated by the merchant.
This value is read-only and set by Rainforest at this time.'
underwriting_reviews:
type: object
nullable: true
description: 'Underwriting review types when an application is in the status of `Needs Information` and Rainforest needs additional verification from the merchant before the application can be be approved. See the [review reasons](doc:additional-verification-for-merchant-onboarding#review-reasons) guide for requirements on each review type.
Keys will be set for the underwriting review types that are applicable to the merchant application.
If no underwriting review types are required, this value will be `null`.'
properties:
business_name_tin:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/underwriting_reviews/properties/other'
description: 'Business name and TIN underwriting review type. Requires the merchant to review and update their business''s legal name and/or TIN.
This key is not present if business name and TIN review is not applicable to the merchant application.'
business_verification:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/underwriting_reviews/properties/financial_1'
description: 'Business verification underwriting review type. Requires the merchant to upload documents to verify their business registration.
This key is not present if it is not applicable to the merchant application.'
deposit_method_1:
description: 'Deposit method underwriting review type. Requires the merchant to update their funding bank account or upload a document, such as bank letter or voided check.
This key is not present if it is not applicable to the merchant application.'
type: object
properties:
updated_at:
type: string
readOnly: true
nullable: true
description: Last updated date in UTC RFC 3339 format.
format: date-time
example: '2022-01-01T12:00:00Z'
file_upload_id:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/underwriting_reviews/properties/financial_1/properties/file_upload_ids/items'
nullable: true
deposit_route_key:
type: string
readOnly: true
description: 'The deposit method requiring underwriting review corresponds to a deposit method as defined in the merchant application''s `deposit_routes` object.
This value is the corresponding key from the merchant application''s `deposit_routes` object.
As of now, this value will always be `PAYMENTS`.'
deposit_method_id:
type: string
readOnly: true
description: 'The corresponding deposit method ID from the `deposit_routes` object for the `deposit_route_key` key.
Prefix is "dmt" in production and "sbx_dmt" in sandbox.'
deposit_method_2:
description: 'Deposit method underwriting review type. Requires the merchant to update their billing bank account or upload a document, such as bank letter or voided check. Only applicable to merchants on Gross billing.
This key is not present if it is not applicable to the merchant application.'
type: object
properties:
updated_at:
type: string
readOnly: true
nullable: true
description: Last updated date in UTC RFC 3339 format.
format: date-time
example: '2022-01-01T12:00:00Z'
file_upload_id:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/underwriting_reviews/properties/financial_1/properties/file_upload_ids/items'
nullable: true
deposit_route_key:
type: string
readOnly: true
description: 'The deposit method requiring underwriting review corresponds to a deposit method as defined in the merchant application''s `deposit_routes` object.
This value is the corresponding key from the merchant application''s `deposit_routes` object.
As of now, this value will always be `BILLING`.'
deposit_method_id:
type: string
readOnly: true
description: 'The corresponding deposit method ID from the `deposit_routes` object for the `deposit_route_key` key.
Prefix is "dmt" in production and "sbx_dmt" in sandbox.'
financial_1:
description: 'Financial review underwriting review type. Requires the merchant to upload documents to complete a financial review, including processing statements or bank statements.
This key is not present if it is not applicable to the merchant application.'
type: object
properties:
updated_at:
type: string
readOnly: true
nullable: true
description: Last updated date in UTC RFC 3339 format.
format: date-time
example: '2022-01-01T12:00:00Z'
file_upload_ids:
type: array
items:
description: "The unique file upload identifier. \n\nPrefix is \"fiu\" in production and \"sbx_fiu\" in sandbox."
type: string
example: fiu_2DrDU206kzAhclm1WrZbuwDERRk
description: List of file upload IDs.
nullable: true
financial_2:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/underwriting_reviews/properties/financial_1'
description: 'Financial review underwriting review type. Requires the merchant to upload documents to complete a financial review, including processing statements, bank statements, and financial statements.
This key is not present if it is not applicable to the merchant application.'
owner_1_name_ssn:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/underwriting_reviews/properties/other'
description: 'Owner 1 underwriting review type. Requires the merchant to review and update the first name, last name, and/or SSN for owner #1.
This key is not present if it is not applicable to the merchant application.'
owner_2_name_ssn:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/underwriting_reviews/properties/other'
description: 'Owner 2 underwriting review type. Requires the merchant to review and update the first name, last name, and/or SSN for owner #2.
This key is not present if it is not applicable to the merchant application.'
owner_3_name_ssn:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/underwriting_reviews/properties/other'
description: 'Owner 3 underwriting review type. Requires the merchant to review and update the first name, last name, and/or SSN for owner #3.
This key is not present if it is not applicable to the merchant application.'
owner_4_name_ssn:
$ref: '#/paths/~1v1~1merchants~1%7Bmerchant_id%7D~1applications~1%7Bmerchant_application_id%7D/patch/requestBody/content/application~1json/schema/properties/underwriting_reviews/properties/other'
description: 'Owner 4 underwriting review type. Requires the merchant to review and update the first name, last name, and/or SSN for owner #4.
This key is not present if it is not applicable to the merchant application.'
other:
description: 'Other underwriting review type. Requires additional verification that cannot be completed through the Merchant Onboarding Component. Rainforest support will reach out to the platform for additional information.
This key is not present if it is not applicable to the merchant application.'
type: object
readOnly: true
properties:
updated_at:
type: string
readOnly: true
nullable: true
description: Last updated date in UTC RFC 3339 format.
format: date-time
example: '2022-01-01T12:00:00Z'
underwriting_verifications:
type: object
nullable: true
description: 'Underwriting verifications triggered by the real-time underwriting verifications flow. See the [real-time underwriting verifications](doc:real-time-underwriting-verifications#direct-api-integration) guide for details.
Values will be set for the underwriting verification types that are applicable to the merchant application.
If a given underwriting verification is not a
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rainforest/refs/heads/main/openapi/rainforest-merchant-applications-api-openapi.yml