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

aliasOnboarding typeIs RequiredData typeDescription
representative.firstName

individual.firstName
Company

Individual
YesStringCompany representative's personal or Individual's first name.
representative.lastName

individual.lastName
Company

Individual
YesStringCompany representative's personal or Individual's last name.
company.email

individual.email
Company

Individual
YesStringCompany representative's or Individual's business email address.
representative.birthDate

individual.birthDate
Company

Individual
YesString
Format: YYYY-MM-DD
Company representative's personal or Individual's birth date.
company.nameCompanyYesStringLegal company name
company.phone

individual.phone
Company

Individual
YesStringCompany representative's or Individual's phone number.
company.address

individual.address
Company

Individual
YesAddressCompany 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.operationalAddressCompanyYesAddress
business.urlCompany / IndividualYesStringFor companies - Business Website URL

For individuals - Profile URL (website, blog, social network profile)
business.serviceDescriptionindividualYesStringA description of the services provided by the individual.
business.categoryCompany / IndividualYesStringMCC codes for the offered goods/services
business.bankAccountCompany / IndividualYesStringNumber of the business bank account
business.sortCodeCompany / IndividualYesStringSort code of the business bank account
business.agreementCompany / IndividualYesAgreementDigital 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 'file=@"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.

aliasIs RequiredTypeDescription
company.incorporationDocumentCompanyYesFileCompany incorporation documents
company.utilityBill

individual.utilityBill
Company

Individual
Optional or ConditionalFileMay be required for both companies and individuals for proof of address
representative.passport

individual.passport
Company

Individual
Optional or ConditionalFileMay be required for both companies and individuals for proof of identity
representative.bankStatement

individual.bankStatement
Company

Individual
Optional or ConditionalFileMay be required for both companies and individuals for proof of bank account ownership
representative.drivingLicense

individual.drivingLicense
Company

Individual
Optional or ConditionalFileMay 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.