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 the onboardingResult object:

🚧

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

1. Redirect the vendor to the UNIPaaS hosted or embedded UI, in that case the UI will request the missing information automatically.
2. 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": […]
}