onboarding/update webhook

Onboarding webhook notifications

Subscribe to the onboarding/update webhook to get notifications about your vendor's every status change.
You'll receive a webhook notification to your server indicating the current status.

Note:
The body will include theonboardingResult object:

Parameter	Always Available	Type	Description
`vendorId`	Yes	String	Vendor unique identifier
`vendorName`	No	String	Once your vendor has initiated the onboarding process and submitted the first form, you will be able to see the vendor's name.
`onboardingStatus`	Yes	Enum	`PENDING` - A vendor has been created. `STARTED` - A vendor has loaded the onboarding component or submitted some of of the fields. `ACTION_REQUIRED` - Vendor has to complete additional fields or confirm already completed fields. `IN_REVIEW` - The Vendor has completed at least one full step of the onboarding process, is being reviewed by UNIPaaS. `RESTRICTED` - Indicates that the vendor has provided all the required information needed for the onboarding flow and can now accept payments and receive payouts up to a limited amount. `ACCEPT_PAYMENTS` - Indicates that a vendor has finished the first step of the onboarding process and can now accept payments. `COMPLETED`- The Vendor has finished the entire onboarding process, and is now allowed to both accept payments and perform payouts. `REJECTED` - The vendor failed the verification process and cannot accept payments or perform payouts.
`status`	Yes	Enum	Gives further detail around the status of the onboardingStatus field. For example: onboardingStatus = `STARTED` status = `PENDING` onboardingStatus = `COMPLETED` status = `ACCEPT_PAYOUT`
`acceptPayments`	Yes	Boolean	`STARTED` - A vendor has loaded the onboarding component or submitted some of of the fields.Indicates if the vendor can currently accept payments
`receivePayout`	Yes	Boolean	Indicates if the vendor can currently receive payouts
`onboardingLink`	No	String	A Link to the onboarding forms
`reference`	No	String	Unique value that represents merchant's user
`actions`	No	Array	All needed actions for this specific onboarding
`type`	Yes	String	Indicates the vendor's business structure (Limited company, Sole trader)
`completionRate`	Yes	Number	Indicates the % of the onboarding process that was completed by the vendor
`pendingFields`	Yes	Array	A list of all the fields that are in `PENDING` status and are required (or optional) for the vendor to fill in order to complete the onboarding process

🚧
Sending Emails to vendors from your system
In case you plan to use these webhook notifications to send emails from your system, you should communicate that to UniPaaS during your integration, to make sure UniPaaS emails are disabled.

Webhook notifications examples

Vendor can accept payments

The following webhook notification demonstrates a vendor receiving an onboarding status of “ACCEPT_PAYMENTS” and the “acceptPayments” flag is set to ‘true’. This means that the vendor can now accept payments within some limitations.

{
  "vendorId": "6182642552aa4acdda1b9926",
  "vendorName": "John Doe",
  "onboardingStatus": "ACCEPT_PAYMENTS",
  "acceptPayments": true,
  "receivePayout": false,
  "type": "individual",
  "completionRate": 50,
  "pendingFields": […]
}

Vendor has been approved

The following webhook notification example demonstrates a vendor that has successfully completed the full onboarding process and now has no limitations on accepting payments and withdrawing funds.

{
  "vendorId": "6182642552aa4acdda1b9926",
  "vendorName": "John Doe",
  "onboardingStatus": "COMPLETED",
  "acceptPayments": true,
  "receivePayout":true,
  "type": "individual",
  "completionRate": 100,
  "pendingFields": […]
}

Vendor is restricted

The following webhook notification example demonstrates a vendor that has not yet been fully approved by UNIPaaS, but has completed the onboarding flow and can both accept payment and receive payouts up to a limited amount. These limitations will be removed one the vendor is fully approved by UNIPaaS.

{
  "vendorId": "6182642552aa4acdda1b9926",
  "vendorName": "John Doe",
  "onboardingStatus": "RESTRICTED",
  "acceptPayments": true,
  "receivePayout": true,
  "type": "individual",
  "completionRate": 100,
  "pendingFields": […]
}

Vendor is in review

The following webhook notification example demonstrates a vendor that has completed the full onboarding process and accepted a payment, this vendor is now under review by UNIPaaS.

{
  "vendorId": "6182642552aa4acdda1b9926",
  "vendorName": "John Doe",
  "onboardingStatus": "IN_REVIEW",
  "acceptPayments": true,
  "receivePayout": false,
  "type": "individual",
  "completionRate": 100,
  "pendingFields": […]
}

Note that while a vendor is in review, he can still accept payments and/or receive payouts in some cases. This is indicated by theacceptPaymetns and receivePayout fields respectively.

Vendor failed to complete onboarding flow within 30 days

The following webhook notification example demonstrates a vendor that has not completed the full onboarding flow during the maximal 30 day period, from when he received his first payment, and therefore, cannot accept additional payments until he completes the full onboarding process.

{
  "vendorId": "6182642552aa4acdda1b9926",
  "vendorName": "John Doe",
  "onboardingStatus": "ACTION_REQUIRED",
  "actions": ["ACTIVATION_DEADLINE_REACHED"],
  "acceptPayments": false,
  "receivePayout": false,
  "type": "individual",
  "completionRate": 50,
  "pendingFields": […]
}

Vendor has accepted the maximum amount of payments

The following webhook notification example demonstrates a vendor that has reached his maximum aggregate payments amount, before he was fully approved by UNIPaaS (this means that the vendor did not reach the'Completed' status). The vendor cannot accept any additional payments until he is approved by UNIPaaS.

{
  "vendorId": "6182642552aa4acdda1b9926",
  "vendorName": "John Doe",
  "onboardingStatus": "ACTION_REQUIRED",
  "actions": ["PAYMENTS_LIMIT_REACHED"],
  "acceptPayments":false,
  "receivePayout": true,
  "type": "individual",
  "completionRate": 50,
  "pendingFields": […]
}

Note that while a vendor has reached his maximum payments limit will still be able to receive payouts, in most cases.

Additional information is needed from the vendor

The following webhook notification example demonstrates a vendor that was requested to provide additional information during his onboarding process.
There are two ways to help the vendor submit the missing information:

Redirect the vendor to the UNIPaaS hosted or embedded UI, in that case the UI will request the missing information automatically.
Collect the missing information from the vendor and submit it via the API. The pendingFields object contains all the filed names that must be submitted (these fields have a PENDING status)

{
  "vendorId": "6182642552aa4acdda1b9926",
  "vendorName": "John Doe",
  "onboardingStatus": "ACTION_REQUIRED",
  "actions": ["ADDITIONAL_INFORMATION"],
  "acceptPayments":false,
  "receivePayout": true,
  "type": "company",
  "completionRate": 85,
  "pendingFields": [
    {
      "alias": "company.registrationNumber",
      "status": "PENDING",
      "required": true,
      "errors": null,
      "value": "12312312"
    },
    {
      "alias": "company.name",
      "status": "PENDING",
      "required": true,
      "errors": null,
      "value": "UNIPaaS"
    }
  ]
}

Vendor was rejected as onboarding flow was not completed with the maximum timeframe

The following webhook notification example demonstrates a vendor that has not completed the onboarding flow while he was already in ACTION_REQUIRED status for over 30 additional days. In this case the vendor will be REJECTED and will not be able to accept payments or withdraw funds.

{
  "vendorId": "6182642552aa4acdda1b9926",
  "vendorName": "John Doe",
  "onboardingStatus": "REJECTED",
  "acceptPayments": false,
  "receivePayout": false,
  "type": "individual",
  "completionRate": 50,
  "pendingFields": […]
}