# Hosted Onboarding ## Overview This section provides a comprehensive guide for Main Account holders who wish to onboard Sub-Accounts onto the Ryft platform using the **Hosted onboarding flow**. This onboarding flow consists of the following three steps: 1. The **Main Account** holder creates a Sub-Account entity using our API. 2. The **Main Account** Holder generates a unique onboarding link and shares it with the Sub-Account. 3. The **Sub-Account** uses the link to access the Ryft portal and create their own login. Once registered, the Sub-Account can enter their business and personal information, upload documents for KYC/KYB verification, add their Bank Account details for payouts, select a payout schedule, and visualise all their customers and transactions. ## 1. Create a Sub-Account Entity Before creating a new Sub-Account entity, it's essential to ensure whether the particular Sub-Account has already been onboarded onto the Ryft platform against the Main Account holder's account. ### 1.1 Check if a Sub-Account is already onboarded To check if a Sub-Account has already been onboarded on your account, use the [subAccountAuthorize](/documentation/api/reference/openapi#operation/subAccountAuthorize) endpoint by specifying the following fields: - `email`: the email address for the user who is being onboarded on behalf of the Sub-Account; - `redirectUrl`: The URL to which the user will be redirected once they have completed their authentication. **Request Example:** ```json subAccountAuthorize - Payload Example { "email": "support@ryftpay.com", "redirectUrl": "https://ryftpay.com" } ``` According to the response, you can determine whether the Sub-Account has already been onboarded. 200 - OK If the Sub-Account has already a Ryft account, the response will be: ```json subAccountAuthorize - Response Example { "createdTimestamp": 1631696701, "expiresTimestamp": 1631703901, "url": "https://sandbox-dash.ryftpay.com/signin?atl=123" } ``` In this case, you can redirect the Sub-Account to the provided URL to log in to their Ryft account and skip Steps 1.2 and 2. 404 - Not Found If there's no Sub-Account registered with the provided email, the response will be: ```json subAccountAuthorize - Response Example { "requestId": "d02c1127-731f-48f0-9b11-b2cee79b3731", "code": "404", "errors": [ { "code": "not_found", "message": "No sub account found with this email" } ] } ``` In this case, you can proceed to Step 1.2 to create a new Sub-Account entity. 400 - Not Registered If the Sub-Account entity has been created but they have not yet registered on the Ryft platform, the response will be: ```json subAccountAuthorize - Response Example { "requestId": "d02c1127-731f-48f0-9b11-b2cee79b3731", "code": "400", "errors": [ { "code": "not_found", "message": "The given sub account has not yet been registered - please use /v1/account-links to create a registration link" } ] } ``` In this case, you can proceed to Step 2 to generate a unique onboarding link for the Sub-Account. ### 1.2 Create a new Sub-Account entity If there's no existing Sub-Account registered under your platform for the specified user, you can create a new Sub-Account entity using the [subAccountCreate](/documentation/api/reference/openapi#operation/subAccountCreate) endpoint by specifying the following fields: - `email`: (optional if providing `business`/`individual` details) the email address for the user who is being onboarded on behalf of the Sub-Account. - `onboardingFlow`: (optional) the onboarding flow to be used for the Sub-Account. If not specified, the `Hosted` onboarding flow will be used. - `metadata`: (optional) useful for storing additional information about the Sub-Account. This field can be used to store any custom data that you may need to associate with the Sub-Account. - `entityType`: (optional) the type of entity - either `Business` or `Individual`. - `business` / `individual`: (required if providing `entityType`, optional otherwise) the business or individual details for the Sub-Account. The `entityType` and `business` / `individual` details will be shown to the user on the Ryft onboarding forms and can be overwritten by them during this process **Request Example:** Email only ```json subAccountCreate - Payload Example { "email": "contact@test.com" } ``` Pre-populate Business details ```json subAccountCreate - Payload Example { "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" } } ``` Pre-populate Individual details ```json subAccountCreate - Payload Example { "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" } } } ``` **Response Handling:** 200 - OK On success, you'll receive a response containing the newly created account: ```json subAccountCreate - Response Example { "id": "ac_XXXXXXXX", ... } ``` It is highly recommended to store the `id` in your database. This is needed to process payments on behalf of the Sub-Account. 409 - Conflict If no Sub-Account matching the provided email is found under your marketplace, the following response 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" } ] } ``` This response highlights that a Sub-Account with the given email already exists under your platform. To resolve this, you can authorize the user instead and provide them with a login link as described in Step 1.1. 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. ## 2. Create An Account Link Once the Sub-Account ID is available, a unique onboarding link can be generated using the [accountLinkCreate](/documentation/api/reference/openapi#operation/accountLinkCreate) endpoint and specifying the following fields: - `accountId`: the ID of the Sub-Account that you want to onboard; - `redirectUrl`: the URL to which the user will be redirected once they have completed their authentication; **Request Example:** ```json accountLinkCreate - Payload Example { "accountId": "ac_XXXXXXXX", "redirectUrl": "https://ryftpay.com" } ``` **Response Handling:** 200 - OK On success, you'll receive a response containing the unique onboarding link: ```json accountLinkCreate - Response Example { "createdTimestamp": 1631696701, "expiresTimestamp": 1631703901, "url": "https://sandbox-dash.ryftpay.com/join?l=al_NzEwYzUxOTA1NWQ0YmIwMGMwYzAxMzQyMGM3YzNkNmRkY2VhYzM3MQ" } ``` You can now share the `url` value with the Sub-Account user to allow them to complete their onboarding process. Once the user completes their onboarding, they will be redirected to the specified `redirectUrl`. 4XX / 5XX ```json accountLinkCreate - Response Example { "requestId": "b83f2653-06d7-44a9-a548-5825e8186004", "code": "400", "errors": [ { "code": "invalid_field", "message": "The supplied field did not have the expected structure" } ] } ``` 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. ## 3. Sub-Account Registration Once the Sub-Account has received the unique onboarding link, they can access it to register on the Ryft platform. The registration process will involve the following steps: 1. **Login Creation**: The Sub-Account will create their own login credentials to access the Ryft platform. They will also set up two-factor authentication for added security. 2. **Business and Personal Information**: The Sub-Account will enter their business and personal information, which may include: - Business name, type, and registration number (if applicable); - Individual's first name, last name, email, date of birth, and phone number. - Address details, including line one, city, country, and postal code. 3. **KYC/KYB Verification**: The Sub-Account will upload the necessary documents for KYC (Know Your Customer) or KYB (Know Your Business) verification. This may include: - Proof of identity (e.g., passport, driver's license); - Proof of address (e.g., utility bill, bank statement); - Business registration documents (if applicable). 4. **Bank Account Details**: The Sub-Account will add their bank account details for payouts. This typically includes: - Bank account number; - Sort code or routing number; - Account holder's name. 5. **Payout Schedule**: The Sub-Account can select their preferred payout schedule, which determines how often they receive payouts from their transactions. 6. **Customer and Transaction Overview**: The Sub-Account will have access to a dashboard where they can visualise all their customers and transactions. ## Next Steps Once a registration link has been provided to the Sub-Account, the Main Account’s responsibilities are essentially complete. You can already begin processing payments on their behalf and, if needed, check their verification status. See [here](/documentation/get_started/onboarding/verification) for more details.