Webhook Notifications

Onboarding webhook notifications

If there are any changes to a vendor's onboarding status, you'll receive a webhook notification to your server indicating the current status.

The body will include the onboardingResult 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

STARTED - A vendor has loaded the onboarding component or submitted some of of the fields.

TYPE_CHANGE - This status indicates that a vendor has changed the onboarding type (individual / business).

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.

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.

acceptPayments

Yes

Boolean

Indicates if the vendor can currently accept payments

receivePayout

Yes

Boolean

Indicates if the vendor can currently receive payouts

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

The following webhook notification demonstrates a vendor receiving an onboarding status of “ACCEPT_PAYMETNS” 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": [ … ]
}

The following webhook notification example shows 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": []
}

The following webhook notification example shows a vendor that has completed the full onboarding process and 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 in some cases. This is indicated by the “acceptPaymetns” field.

The following webhook notification example shows a vendor that has not completed the second onboarding step (The Embedded UI) during the maximal 30 day period, from when he received his first payment, and 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": [ … ]
}

The following webhook notification example shows a vendor that has not completed the second onboarding step (The Embedded UI) while accepting payments in the total amount of 1,500GBP (example of payin limitation amount amount), and cannot accept additional payments until he completes the full onboarding process.

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

The following webhook notification example shows a vendor that has not completed the second onboarding step (The Embedded UI) 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": []
}