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 '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.

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.