Onboarding API

Onboard your vendors using our Onboarding API and move them through the KYC/KYB verification process, by building your own onboarding flow.

Before you begin

UNIPaaS makes sure that your customers will have a safe and secure onboarding experience, therefore we will review and approve your integration to confirm all legal and compliance requirements are met.

📘

Choosing this integration option requires you to build your own onboarding front end experience

Create a vendor

Before starting the onboarding process, you must create a vendor in the UNIPaaS system. When creating a vendor, we strongly recommend you send the vendor's type (type = individual or company) as part of the create vendor call. This will allow UNIPaaS to pass the relevant fields for the vendor type.

The following API integration guide will refer to both mentioned vendor types in every step.

Please read how to Create vendor

Get Onboarding fields

If you wish to design a generic solution choose this method to get all the relevant fields for both business and individual onboarding types.
This call can be repeated at any time to receive the remaining fields during the onboarding process.

The alternative is to follow the API requested field table

curl --request GET \
  --url 'https://sandbox.unipaas.com/platform/vendors/{vendorId}/onboarding' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PLATFORM_SECRET_KEY>'

Example for GET Onboarding Fields partial response for companies

{
  "onboardingStatus": "STARTED",
  "acceptPayments": false,
  "receivePayouts": false,
  "fields": [
    {
      "alias": "company.email",
      "value": "[email protected]",
      "status": "COMPLETED"
    },
    {
      "alias": "company.phone",
      "value": "+447911123456",
      "status": "COMPLETED"
    },
    {
      "alias": "representative.firstName",
      "value": "John",
      "status": "PENDING"
    },
    {
      "alias": "representative.lastName",
      "value": "Doe",
      "status": "PENDING"
    },
    {
      "alias": "company.name",
      "value": "Better Delivery",
      "status": "PENDING"
    },
    {
      "alias": "company.address",
      "value": null,
      "status": "PENDING"
    },
     {
      "alias": "company.operationalAddress",
      "value": null,
      "status": "PENDING"
    },
    {
      "alias": "business.category",
      "value": "FOOD_DELIVERY",
      "status": "PENDING"
    },
    {
      "alias": "business.agreement",
      "value": null,
      "status": "PENDING"
    }
  ]
}

Example for GET Onboarding Fields partial response for individuals

{
  "onboardingStatus": "STARTED",
  "acceptPayments": false,
  "receivePayout": false,
  "fields": [
    {
      "alias": "individual.firstName",
      "status": "PENDING",
      "value": "John"
    },
    {
      "alias": "individual.lastName",
      "status": "PENDING",
      "value": "Doe"
    },
    {
      "alias": "individual.birthDate",
      "status": "COMPLETED",
      "value": "1980-01-01"
    },
    {
      "alias": "individual.email",
      "status": "COMPLETED",
      "value": "[email protected]"
    },
    {
      "alias": "individual.phone",
      "status": "PENDING",
      "value": "+447911123456"
    },
    {
      "alias": "individual.address",
      "status": "PENDING",
      "value": null
    },
    {
      "alias": "business.accountHolderName",
      "status": "PENDING",
      "value": null
    },
    {
      "alias": "business.bankAccount",
      "status": "PENDING",
      "value": null
    },
    {
      "alias": "business.sortCode",
      "status": "PENDING",
      "value": null
    },
    {
      "alias": "individual.drivingLicense",
      "required": false,
      "status": "PENDING",
      "value": null,
    },
    { 
      "alias": "business.agreement",
      "value": null,
      "status": "PENDING"
    }
  ]
}

Note that some of the onboarding fields might be already completed as a result of the information you provided during vendor creation.

Onboarding field types

The onboarding fields response example shown above demonstrates several field types, defined by the type property.

Onboarding Endpoints

Use the binary data type specific endpoint to pass files, such as Driving license copy.
For all other information types, use the main onboarding endpoint.

Submitting onboarding information (main endpoint)

Using this method you can pass all the vendor's relevant details.

Example for POST Onboarding Fields partial requests, using the main endpoint

For Companies:

curl --request POST \
  --url 'https://sandbox.unipaas.com/platform/vendors/{vendorId}/onboarding' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PLATFORM_SECRET_KEY>' \
  --data-raw '{
  "fields": [
    {
      "alias": "company.name",
      "value": "Better Delivery"
    },
    {
      "alias": "business.agreement",
      "value": {
        "accepted": true,
        "ipAddress": "1.1.1.1"
      }
    },
    {
      "alias": "business.category",
      "value": "FOOD_DELIVERY"
    }
  ]
}'

For individuals:

curl --request POST \
  --url 'https://sandbox.unipaas.com/platform/vendors/{vendorId}/onboarding' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PLATFORM_SECRET_KEY>' \
  --data-raw '{
   "fields":[
      {
        "alias": "individual.address",
        "value": {
          "country": "GB",
          "city": "London",
          "street": "New Cavendish Street",
          "houseNumber": "64",
          "postCode": "W1G 8TB"
        }
      },
      {
        "alias": "business.bankAccount",
        "value": "38290008"
      },
      {
        "alias": "business.sortCode",
        "value": "200415"
      }
    ]
}'

Example for partial POST Onboarding Fields response

For Companies:

{
  "onboardingStatus": "STARTED",
  "acceptPayments": false,
  "receivePayout": false,
  "fields": [
    {
      "alias": "representative.firstName",
      "type": "TEXT_FIELD",
      "status": "PENDING",
      "value": "John"
    },
    {
      "alias": "representative.lastName",
      "type": "TEXT_FIELD",
      "status": "PENDING",
      "value": "Doe"
    },
    {
      "alias": "company.name",
      "status": "COMPLETED",
      "value": "Better Delivery"
    },
    {
      "alias": "company.email",
      "status": "COMPLETED",
      "value": "[email protected]"
    },
    {
      "alias": "company.phone",
      "status": "COMPLETED",
      "value": "+447911123456"
    },
    {
      "alias": "company.address",
      "status": "COMPLETED",
      "value": {
        "country": "GB",
        "city": "London",
        "street": "New Cavendish Street",
        "houseNumber": "64",
        "postCode": "W1G 8TB",
      }
    },
     {
      "alias": "company.operationalAddress",
      "status": "COMPLETED",
      "value": {
        "country": "GB",
        "city": "London",
        "street": "New Cavendish Street",
        "houseNumber": "64",
        "postCode": "W1G 8TB",
      }
    }
  ]
}

For individuals:

{
  "onboardingStatus": "STARTED",
  "acceptPayments": false,
  "receivePayout": false,
  "fields": [
    {
      "alias": "individual.firstName",
      "status": "COMPLETED",
      "value": "John",
    },
    {
      "alias": "individual.lastName",
      "status": "COMPLETED",
      "value": "Doe",
    },
    {
      "alias": "individual.birthDate",
      "status": "COMPLETED",
      "value": "1980-01-01"
    },
    {
      "alias": "individual.email",
      "status": "COMPLETED",
      "value": "[email protected]"
    },
    {
      "alias": "individual.phone",
      "status": "COMPLETED",
      "value": "+447911123456",
    },
    {
      "alias": "individual.address",
      "status": "COMPLETED",
      "value": {
        "country": "GB",
        "city": "London",
        "street": "New Cavendish Street",
        "houseNumber": "64",
        "postCode": "W1G 8TB",
      }
    },
    {
      "alias": "business.bankAccount",
      "status": "COMPLETED",
      "value": "38290008"
    },
    {
      "alias": "business.sortCode",
      "status": "COMPLETED",
      "value": "200415"
    },
    {
      "type": "FILE_INPUT",
      "alias": "individual.drivingLicense",
      "status": "PENDING",
      "value": null,
    }
  ]
}

Onboarding API requested fields

alias

Onboarding type

Is Required

Data type

Description

representative.firstName

individual.firstName

Company

Individual

Yes

String

Company representative's personal or Individual's first name.

representative.lastName

individual.lastName

Company

Individual

Yes

String

Company representative's personal or Individual's last name.

company.email

individual.email

Company

Individual

Yes

String

Company representative's or Individual's business email address.

representative.birthDate

individual.birthDate

Company

Individual

Yes

String
Format: YYYY-MM-DD

Company representative's personal or Individual's birth date.

company.name

Company

Yes

String

Legal company name

company.phone

individual.phone

Company

Individual

Yes

String

Company representative's or Individual's phone number.

company.address

individual.address

Company

Individual

Yes

Address

Company corporate or Individual's address

country: string, ISO 3166-1 alpha-2 code
city: string
street: string
houseNumber: string
flatNumber: string (optional)
postCode: string

company.operationalAddress

Company

Yes

Address

business.url

Company / Individual

Yes

String

For companies - Business Website URL

For individuals - Profile URL (website, blog, social network profile)

business.serviceDescription

individual

Yes

String

A description of the services provided by the individual.

business.category

Company / Individual

Yes

String

MCC codes for the offered goods/services

business.bankAccount

Company / Individual

Yes

String

Number of the business bank account

business.sortCode

Company / Individual

Yes

String

Sort code of the business bank account

business.agreement

Company / Individual

Yes

Agreement

Digital signature on the MSA

accepted: Boolean,
ipAddress: ip

Submitting onboarding files (binary endpoint)

Example of JS code for implementing POST Onboarding File request

<!DOCTYPE html>
<html>
<body>
  <input id="file-input" type="file">
  <script type="text/javascript">
    const fileInput = document.getElementById("file-input")
    fileInput.onchange = async function(e){
      const file = new File(['drivingLicense'], fileInput.value, {
        type: 'image/png',
      });

      const formData = new FormData();
      formData.append('file', file, file.name);
      formData.append('alias', 'drivingLicense');
      await fetch('https://sandbox.unipaas.com/platform/vendors/{vendorId}/onboarding/file', {
        method: 'post',
        body: formData,
        headers: { 'Authorization': 'Bearer <Bearer Token>' },
      });
    }
  </script>
</body>
</html>

Example for POST Onboarding File request

curl --location --request POST 
'https://sandbox.unipaas.com/platform/vendors/{vendorId}/onboarding/file' \
--header 'Authorization: Bearer <PLATFORM_SECRET_KEY>' \
--form 'alias="individual.drivingLicense"' \
--form '[email protected]"drivingLicense.png"'

Example for POST Onboarding File response

{
  "onboardingStatus": "STARTED",
  "acceptPayments": false,
  "receivePayout": false,
  "fields": [
    
    ...
             
    {
      "alias": "individual.drivingLicense",
      "status": "COMPLETED",
      "value": {
        "name": "drivingLicense.png",
        "size": 42115
      }
    }
  ]
}

Onboarding API requested fields

Please note that submitting Incorporation documents, Passport or Driving license is mandatory to approve vendors for payout.
In some cases we will need extra files, including but not limited to Utility bill or Bank statement to approve the vendor.

alias

Is Required

Type

Description

company.incorporationDocument

Company

Yes

File

Company incorporation documents

company.utilityBill

individual.utilityBill

Company

Individual

Optional or Conditional

File

May be required for both companies and individuals for proof of address

representative.passport

individual.passport

Company

Individual

Optional or Conditional

File

May be required for both companies and individuals for proof of identity

representative.bankStatement

individual.bankStatement

Company

Individual

Optional or Conditional

File

May be required for both companies and individuals for proof of bank account ownership

representative.drivingLicense

individual.drivingLicense

Company

Individual

Optional or Conditional

File

May be required for both companies and individuals for proof of identity

Optional onboarding fields

Some of the onboarding fields may be optional. It is not mandatory to populate these fields to complete the onboarding process. In order to improve your vendor acceptance rates, we do recommend filling these fields anyway.

Optional fields can be identified by their required: false, parameter, as per the following example:

{
      "label": "Driving license",
      "type": "FILE_INPUT",
      "alias": "individual.drivingLicense",
      "required": false,
      "status": "PENDING",
      "completedAt": null,
      "value": null,
      "errors": null
}

In case any of the optional fields will be required to complete the vendor's verification process, the "required": false property will be removed from that specific field, and it will become mandatory.