Consumer Onboarding

This tutorial walks you through the basic steps of integrating your fintech product with the Upwardli platform. In the documentation we describe both a UI-only and API + UI hybrid integration.

Summary

Consumer onboarding is a fully asynchronous process due to the KYC and Banking integrations, which are themselves asynchronous. Our design goal for a user interacting with the Onboarding component is to capture data in realtime, and then process asychronously. This will reduce elapsed customer interaction time and improve the user experience.

UI Onboarding Walkthrough:

The following steps outline the steps encountered when onboarding a new consumer via our UI Components.

[Customer] loads the onboarding embedded component in your app.

When you load the onboarding embedded component passing in the pcid property (your unique ID) as a query parameter. Once the customer clicks “Get Started”, the UI component creates their consumer record using the Consumer API endpoint. The user’s pcid will be set to the value you provide us, and we will generate a unique id on our side to identify this record internally and within our APIs.

[Upwardli] sends out a consumer.created webhook message to your server.

The Upwardli Severs will send a webhook message to you with the following general schema, indicating that the consumer record was created on our side.

1{
2  "id": "ea04f0a8-b005-47cd-ba33-b02a00c0c426",
3  "created_at": "2023-06-23T07:41:50.45-04:00",
4  "event_name": "consumer.created",
5  "partner_id": "2f221c90-b82d-4e12-9bfd-ae8301097de3",
6  "resources": [
7    "https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}"
8  ],
9  "last_attempted_at": "2023-06-23T07:41:50.45-04:00"
10}

Upon receiving the webhook messge, you will parse it for the eventName property and determine that this message means that a new consumer was created. You can then call the url in the resources property to get information about that consumer.

1{
2    "id": "{consumer_id}",
3    "pcid": "{pcid}",
4    "first_name": null,
5    "last_name": null,
6    "email": null,
7    "is_active": true,
8    "kyc_status": "NotStarted",
9    "phone_number": null,
10    "date_of_birth": null,
11    "tax_id_type": "SSN",
12    "tax_identifier": null,
13    "address_line1": null,
14    "address_line2": null
15}
Note

at the time of creation, the user has not completed KYC, so their personal data has not been captured and will be null in the response body_

[Consumer] Completes the KYC step(s)

Once the user has successfully completed KYC, then we will send a further webhook with an event_name of consumer.updated

1{
2  "id": "ea04f0a8-b005-47cd-ba33-b02a00c0c426",
3  "created_at": "2023-06-23T07:41:50.45-04:00",
4  "event_name": "consumer.updated",
5  "partner_id": "2f221c90-b82d-4e12-9bfd-ae8301097de3",
6  "resources": [
7    "https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}"
8  ],
9  "last_attempted_at": "2023-06-23T07:41:50.45-04:00"
10}

When you retrieve the updated consumer record related to this webhook, you will see that the kyc_status value has changed to complete indicating that this consumer has successfully passed our KYC checks.

1{
2    "id": "{consumer_id}",
3    "pcid": "{pcid}",
4    "first_name": "John",
5    "last_name": "Doe",
6    "email": "john.doe@gmail.com",
7    "is_active": true,
8    "kyc_status": "Complete",
9    "phone_number": "+12065559034",
10    "date_of_birth": "2000-01-01",
11    "tax_id_type": "SSN",
12    "tax_identifier": "***-**-1234",
13    "address_line1": "100 Main Street",
14    "address_line2": null
15}
Tip

In the event that you do not receive the webhook or there are data processing/sync issues on your end, you can always call the get consumer by Partner Consumer ID endpoint: GET https://sandbox-api.upwardli.com/v2/consumer/pcid/{pcid}/ where the {pcid} property is the internal ID you provided as a query parameter to the onboarding component.

Optional: KYC Data Pre-Fill

Before redirecting the user to our page, you can prepopulate data for a consumer by calling the api: POST: https://sandbox-api.upwardli.com/v2/consumer/ and providing the following fields:

1{
2    "pcid": "{pcid}",
3    "first_name": "John",
4    "last_name": "Doe",
5    "email": "john.doe@email.com",
6    "phone_number": "+12065559034",
7    "date_of_birth": "2000-01-01",
8    "address_line1": "100 Main Street",
9    "address_line2": "Apt 123"
10}
Note

all fields are optional except for pcid_

Edge Cases / Unhappy path:

  1. If a user does not complete KYC, then you will only receive the first consumer.created message.
  2. If a user fails KYC, then we will send a consumer.updated webhook, with a kyc_status value of Failed. We will not open a credit line for any users who do not pass KYC.
Built with