# Non-Hosted (API) Onboarding

## Overview

This section provides a guide for Main Account holders that wish to onboard Sub-Accounts onto the Ryft platform using the **Non-Hosted (API)** onboarding flow.

The Non-Hosted onboarding flow is fully API-driven and performed by the Main Account holder. It consists of the following steps:

1. Create a Sub-Account entity;
2. (Business entities only) Create one or more Person entities for the given Business;
3. Upload the required documents for KYC/KYB verification;
4. Set up the Bank Account details for payouts;
5. Redirect the Sub-Account to the Ryft Terms & Conditions for acceptance;


**Please Note**: Steps 3, 4 and 5 can be performed in any order, but all of them must be completed before the Sub-Account can start receiving payouts.

## Create a Sub-Account Entity

The first step to create a Sub-Account is to use the Ryft Accounts API to create a new Sub-Account entity. This can be done using the [subAccountCreate](/documentation/api/reference/openapi#operation/subAccountCreate) endpoint with the necessary details of the Sub-Account. The request should include the following information:

- `onboardingFlow`: Set this to `NonHosted` to indicate that this is a Non-Hosted onboarding flow.
- `entityType`: Defines the type of entity being created (e.g., `Individual`, `Business`). It will also determine how it will be verified.
  - If `Individual`, the Sub-Account will be verified using KYC (Know Your Customer) procedures.
  - If `Business`, it will be verified using KYB (Know Your Business) procedures. Although this field isn't mandatory at the time of creation and you can still process payments on their behalf, payout methods (and therefore issuing payouts) won't be available until the Sub-Account is fully verified.
- `metadata`: (optional) Any additional metadata you wish to associate with the Sub-Account.


The Accounts API does not mandate all fields for either `entityType`. However, it is recommended to provide as much information as possible to ensure a smooth onboarding process.

**Example Request**:

Create Minimum Account

```json subAccountCreate - Payload Example
{
    "onboardingFlow": "NonHosted",
    "metadata": {
        "yourAccountId": "123"
    }
}
```

Create Individual Entity

```json subAccountCreate - Payload Example
{
    "onboardingFlow": "NonHosted",
    "entityType": "Individual",
    "individual": {
        "firstName": "Fred",
        "lastName": "Jones",
        "email": "fred.jones@example.com",
        "dateOfBirth": "1990-01-20",
        "gender": "Male",
        "nationalities": ["GB"],
        "address": {
            "lineOne": "123 Road",
            "city": "London",
            "country": "GB",
            "postalCode": "SW1 1AA"
        }
    },
    "metadata": {
        "yourAccountId": "123"
    }
}
```

Create Business Entity
If the entity you're onboarding does not have a `registrationNumber`, then create them as an **Individual** instead.


```json subAccountCreate - Payload Example
{
    "onboardingFlow": "NonHosted",
    "entityType": "Business",
    "business": {
        "name": "Test Ltd",
        "type": "PublicCompany",
        "registrationNumber": "12345678",
        "registeredAddress": {
            "lineOne": "123 Street",
            "city": "Manchester",
            "country": "GB",
            "postalCode": "M1 1AA"
        },
        "contactEmail": "contact@test.com"
    },
    "metadata": {
        "yourAccountId": "123"
    }
}
```

**Response Handling**:

200 OK
On success, a response containing the newly created account will be returned


```json subAccountCreate - Response Example
{
    "id": "ac_XXXXXXXX",
    "type": "Sub",
    "entityType": "Business",
    "onboardingFlow": "NonHosted",
    "business": {
        "name": "Test Ltd",
        "type": "PublicCompany",
        "registrationNumber": "12345678",
        "registeredAddress": {
            "lineOne": "123 Street",
            "city": "Manchester",
            "country": "GB",
            "postalCode": "M1 1AA"
        },
        "contactEmail": "contact@test.com"
    },
    "frozen": false,
    "verification": {...} // see Verifying accounts section for more detail
    "metadata": {
        "yourAccountId": "123"
    }
}
```

409 - Conflict
If a Sub-Account entity has already been created previously under your platform with the provided details, the following reponse will be returned.


```json subAccountCreate - Response Example
{
    "requestId": "d02c1127-731f-48f0-9b11-b2cee79b3731",
    "code": "409",
    "errors": [
        {
            "code": "bad_request",
            "message": "A resource with these details already exists"
        }
    ]
}
```

4XX / 5XX

```json subAccountCreate - Response Example
    {
    "requestId": "d02c1127-731f-48f0-9b11-b2cee79b3731",
    "code": "400",
    "errors": [
        {
            "code": "bad_request",
            "message": "The given email is not valid"
        }
    ]
}
```

In this case, you should inspect the error message:

- If a bad request is returned, you should attempt to resolve the issue;
- If a 5XX is returned, you may retry the request. If it keeps failing, please reach out to support for assistance.


## Next Steps

Once the Sub-Account entity is created, you can immediately start processing payments on behalf of the Sub-Account entity.

However, to issue payouts to the Sub-Account, you must first complete the following steps:

- Upload the required documents for KYC/KYB verification - see [here](/documentation/get_started/onboarding/verification);
- Set up the Bank Account details for payouts - see [here](/documentation/get_started/onboarding/payouts);
- Redirect the Sub-Account to the Ryft Terms & Conditions for acceptance - see [here](/documentation/get_started/onboarding/terms_conditions).