Skip to content
/
Hosted Onboarding
Last updated

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 endpoint by specifying the following fields:

  • email: the email address for the user who is being oboarded on behalf of the Sub-Account;
  • redirectUrl: The URL to which the user will be redirected once they have completed their authentication.

Request Example:

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.

If the Sub-Account has already a Ryft account, the response will be:

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.

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 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:

subAccountCreate - Payload Example
{
    "email": "contact@test.com"
}

Response Handling:

On success, you'll receive a response containing the newly created account:

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.

Once the Sub-Account ID is available, a unique onboarding link can be generated using the 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:

accountLinkCreate - Payload Example
{
    "accountId": "ac_XXXXXXXX",
    "redirectUrl": "https://ryftpay.com"
}

Response Handling:

On success, you'll receive a response containing the unique onboarding link:

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.

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 for more details.

Previous page
Next page