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:
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 | The same statuses as in onboardingStatus field |
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 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:
- 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": […]
}
Updated about 2 months ago