logo

Onboarding via API

In order to process payments, each of your customers (whom we refer to as sub accounts) will go through an approval process. JustiFi's onboarding API allows you to utilize your own onboarding frontend to collect the required business and financial information from each of your sub accounts. Once approved, your sub account can process payments through JustiFi.

To onboard a new sub account via the API

  1. Create a sub account
  2. Create an onboarding entry
  3. Check the sub account's status

Create a sub account

Create a sub account

curl -X POST \
  https://api.justifi.ai/v1/sub_accounts \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sub account name"
  }'

Use the sub accounts API to create a sub account on JustiFi that is associated with your platform. You will need the account_id from the sub account you create for the next step.

Create an onboarding entry

Use the onboarding API to create an onboarding entry containing the required information for the sub account you made.

Check the sub account status

Retrieve a sub account

curl -X GET https://api.justifi.ai/v1/sub_accounts/ACCOUNT_ID \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'

Once you create the account's onboarding entry, we'll review their information. This approval process can take up to a few business days. In order to check the account's onboarding status, call the Get a Sub Account endpoint or use an event publisher to subscribe to the sub_account.updated events.Note: seller_account.updated event has been deprecated

Create an Onboarding Entry

First, you'll need to create a sub account so you can use that sub account id in the path for this API.

Create an onboarding entry for a sub account, which will send their required onboarding information to the JustiFi team for review. This will change the sub account's status to submitted. Upon review, if we require additional verification in the form of an ID document (which is rare), we'll work with your sub account to obtain the documentation we need.

Depending on each sub account's business type and structure, the onboarding information you'll need to collect will vary. Use the table below to check the requirements for each. You can also get a head start by copying the payloads from the request samples on the right; just choose the type of business you need from the dropdown first. Note: The payload, response, and restrictions are all subject to change based on gateway requirements.

For-Profit Non-Profit Government Entity
Individual Sole Proprietorship Single Member LLC Multi Member LLC Private Partnership Private Corporation Unincorporated Association Public Partnership Public Corporation Incorporated Unincorporated Governmental Unit Government Instrumentality
business_details.url Required for all
business_details.type Required for all
business_details.structure Required for all
business_details.industry Required for all
business_details.tax_id - ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
business_details.phone - - - ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
business_details.email - - - ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
business_details.legal.name - ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
business_details.legal.address* fields - - - ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
business_details.doing_business_as.name Required for none
representative.name Required for all
representative.title - - - ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
representative.email ✅ ✅ ✅ ✅ ✅ ✅ ✅ - - ✅ ✅ - -
representative.phone ✅ ✅ ✅ ✅ ✅ ✅ ✅ - - ✅ ✅ - -
representative.ssn_last4 ✅ ✅ ✅ ✅ ✅ ✅ ✅ - - ✅ ✅ ✅ ✅
representative.is_owner ✅ ✅ ✅ ✅ ✅ ✅ ✅ - - ✅ ✅ - -
representative.dob* fields ✅ ✅ ✅ ✅ ✅ ✅ ✅ - - ✅ ✅ ✅ ✅
representative.address* fields ✅ ✅ ✅ ✅ ✅ ✅ ✅ - - ✅ ✅ - -
owners list - - - ✅ ✅ ✅ ✅ - - - - - -
bank_account Required for all
terms_and_conditions.accepted Required for all
terms_and_conditions.ip Required for all
terms_and_conditions.user_agent Required for none
Request
path Parameters
id
required
string <uuid>

sub account id for which this entry is being submitted

header Parameters
Authorization
required
string

the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)

Example: Bearer {access_token}
Request Body schema: application/json
onboarding_version
string

defaults to v1.0 if not passed, may change in the future as onboarding requirements change

object

information about the sub account's business, as defined on their SS-4 tax document

object

personal information about the financial representative -- this must be someone who has significant control over managing this sub account's finances

Array of objects

up to four business owners total; do not re-record the financial representative if they are marked as an owner

object

bank account which will be used for payouts to the sub account (must be a US-based checking account)

object

details about accepting JustiFi's terms and conditions on behalf of a sub account

Responses
200

Onboarding entry was created successfully

post/onboarding/{id}
Request samples
application/json
{
  • "business_details": {},
  • "representative": {
    },
  • "bank_account": {
    },
  • "terms_and_conditions": {
    }
}
Response samples
application/json
{
  • "id": 1,
  • "type": "onboarding_entry",
  • "data": {
    },
  • "page_info": "string"
}
➔ Next to Proceeds