Handling a Fallback KYC Inquiry

During API-based onboarding, when a consumer fails a KYC database-check you can choose to have them complete secondary validations such as document collection and selfie/image verification directly in your application. The process will be to use the value of the fallback_inquiry_id property from the consumer’s onboarding workflow to load a KYC component in your application configured for that user’s specific KYC next steps.

Scenario: Consumer Fails KYC Database Check

When a user fails a KYC database check after the Verify Identity step, we will provide a fallback_inquiry_id in the workflow api response.

The two properties to look for in this api response are:

consumer->kyc_status == NeedsReview
kyc->fallback_inquiry_id => value

1 {
2   "id": "bcc76111-2451-4299-a02d-3f067cf3ca5a",
3   "status": "new",
4   "consumer": {
5     "id": "af593b07-be91-4a18-84c6-7bbb8110faa6",
6     "pcid": "card-10a20110-2c8f-4c3f-a7db-f1999c33e24e",
7     "mla_status": false,
8     "first_name": "Test",
9     "last_name": "User",
10     "email": "consumer@email.com",
11     "is_active": true,
12     "kyc_status": "NeedsReview",
13     "phone_number": "+15555555555",
14     "date_of_birth": "1957-09-06",
15     "tax_id_type": "SSN",
16     "tax_identifier": "***-**-1377",
17     "address_line1": "86782 Rosemarie Freeway",
18     "address_line2": null,
19     "address_city": "Ottilieworth",
20     "address_state": "AL",
21     "address_zip": "35405"
22   },
23   "kyc": {
24     "inquiry_ids": [
25       "txn_xxxxxxxxxxxxxxxxxh"
26     ],
27     "fallback_inquiry_id": "inq_EXAMPLE",
28     "inquiry_template_id": "itmpl_xxxxxxxxxxxxxxxx",
29     "errors": []
30   },
31   "e_sign": {
32     "agreement_accepted": null,
33     "agreement_accepted_date": null
34   },
35   "underwriting": {
36     "result": null,
37     "data": null,
38     "errors": null
39   },
40   "product": {
41     "product_id": "11111111-1000-0000-0000-000000000001",
42   },
43   "previous_steps": [
44     {
45       "slug": "select_product",
46       "url": "/v2/onboarding/bcc76111-2451-4299-a02d-3f067cf3ca5a/select-product/"
47     },
48     {
49       "slug": "get_started",
50       "url": "/v2/onboarding/bcc76111-2451-4299-a02d-3f067cf3ca5a/"
51     }
52   ],
53   "current_steps": [
54     {
55       "slug": "verify_identity",
56       "url": "/v2/onboarding/bcc76111-2451-4299-a02d-3f067cf3ca5a/verify-identity/"
57     }
58   ],
59   "metadata": null
60 }

Launching the KYC Mobile SDK

Once you have retrieved the fallback_inquiry_id from the api response, your backend servers can provide that value to your mobile application to hydrate the Persona Mobile SDK. Initializing the Mobile SDK with this inquiry template will allow the consumer to complete the KYC portion of their onboarding.

in this scenario, we are assuming a mobile/native app built in React Native

1 javascript
2 
3 
4 import {Inquiry} from 'react-native-persona';
5 // ...
6 <Button
7   title="Start Inquiry"
8   onPress={() => {
9     Inquiry.fromInquiry('inq_EXAMPLE')
10       .onComplete((inquiryId, status, fields) =>
11         Alert.alert(
12           'Complete',
13           'Inquiry ' + inquiryId + ' completed with status "' + status + '."',
14         ),
15       )
16       .onCanceled((inquiryId, sessionToken) =>
17         Alert.alert('Canceled', 'Inquiry ' + inquiryId + ' was cancelled'),
18       )
19       .onError(error => Alert.alert('Error', error.message))
20       .build()
21       .start();
22   }}
23 />

You can read more about integrating the Persona KYC UI components into your mobile app here.

Scenario: Consumer Fails KYC Database Check

When a user fails a KYC database check after the Verify Identity step, we will provide a fallback_inquiry_id in the workflow api response.

The two properties to look for in this api response are:

consumer->kyc_status == NeedsReview
kyc->fallback_inquiry_id => value

1 {
2   "id": "bcc76111-2451-4299-a02d-3f067cf3ca5a",
3   "status": "new",
4   "consumer": {
5     "id": "af593b07-be91-4a18-84c6-7bbb8110faa6",
6     "pcid": "card-10a20110-2c8f-4c3f-a7db-f1999c33e24e",
7     "mla_status": false,
8     "first_name": "Test",
9     "last_name": "User",
10     "email": "consumer@email.com",
11     "is_active": true,
12     "kyc_status": "NeedsReview",
13     "phone_number": "+15555555555",
14     "date_of_birth": "1957-09-06",
15     "tax_id_type": "SSN",
16     "tax_identifier": "***-**-1377",
17     "address_line1": "86782 Rosemarie Freeway",
18     "address_line2": null,
19     "address_city": "Ottilieworth",
20     "address_state": "AL",
21     "address_zip": "35405"
22   },
23   "kyc": {
24     "inquiry_ids": [
25       "txn_xxxxxxxxxxxxxxxxxh"
26     ],
27     "fallback_inquiry_id": "inq_EXAMPLE",
28     "inquiry_template_id": "itmpl_xxxxxxxxxxxxxxxx",
29     "errors": []
30   },
31   "e_sign": {
32     "agreement_accepted": null,
33     "agreement_accepted_date": null
34   },
35   "underwriting": {
36     "result": null,
37     "data": null,
38     "errors": null
39   },
40   "product": {
41     "product_id": "11111111-1000-0000-0000-000000000001",
42   },
43   "previous_steps": [
44     {
45       "slug": "select_product",
46       "url": "/v2/onboarding/bcc76111-2451-4299-a02d-3f067cf3ca5a/select-product/"
47     },
48     {
49       "slug": "get_started",
50       "url": "/v2/onboarding/bcc76111-2451-4299-a02d-3f067cf3ca5a/"
51     }
52   ],
53   "current_steps": [
54     {
55       "slug": "verify_identity",
56       "url": "/v2/onboarding/bcc76111-2451-4299-a02d-3f067cf3ca5a/verify-identity/"
57     }
58   ],
59   "metadata": null
60 }

Launching the KYC Mobile SDK

in this scenario, we are assuming a mobile/native app built in React Native

1 javascript
2 
3 
4 import {Inquiry} from 'react-native-persona';
5 // ...
6 <Button
7   title="Start Inquiry"
8   onPress={() => {
9     Inquiry.fromInquiry('inq_EXAMPLE')
10       .onComplete((inquiryId, status, fields) =>
11         Alert.alert(
12           'Complete',
13           'Inquiry ' + inquiryId + ' completed with status "' + status + '."',
14         ),
15       )
16       .onCanceled((inquiryId, sessionToken) =>
17         Alert.alert('Canceled', 'Inquiry ' + inquiryId + ' was cancelled'),
18       )
19       .onError(error => Alert.alert('Error', error.message))
20       .build()
21       .start();
22   }}
23 />

You can read more about integrating the Persona KYC UI components into your mobile app here.

1	{
2	"id": "bcc76111-2451-4299-a02d-3f067cf3ca5a",
3	"status": "new",
4	"consumer": {
5	"id": "af593b07-be91-4a18-84c6-7bbb8110faa6",
6	"pcid": "card-10a20110-2c8f-4c3f-a7db-f1999c33e24e",
7	"mla_status": false,
8	"first_name": "Test",
9	"last_name": "User",
10	"email": "consumer@email.com",
11	"is_active": true,
12	"kyc_status": "NeedsReview",
13	"phone_number": "+15555555555",
14	"date_of_birth": "1957-09-06",
15	"tax_id_type": "SSN",
16	"tax_identifier": "*--1377",
17	"address_line1": "86782 Rosemarie Freeway",
18	"address_line2": null,
19	"address_city": "Ottilieworth",
20	"address_state": "AL",
21	"address_zip": "35405"
22	},
23	"kyc": {
24	"inquiry_ids": [
25	"txn_xxxxxxxxxxxxxxxxxh"
26	],
27	"fallback_inquiry_id": "inq_EXAMPLE",
28	"inquiry_template_id": "itmpl_xxxxxxxxxxxxxxxx",
29	"errors": []
30	},
31	"e_sign": {
32	"agreement_accepted": null,
33	"agreement_accepted_date": null
34	},
35	"underwriting": {
36	"result": null,
37	"data": null,
38	"errors": null
39	},
40	"product": {
41	"product_id": "11111111-1000-0000-0000-000000000001",
42	},
43	"previous_steps": [
44	{
45	"slug": "select_product",
46	"url": "/v2/onboarding/bcc76111-2451-4299-a02d-3f067cf3ca5a/select-product/"
47	},
48	{
49	"slug": "get_started",
50	"url": "/v2/onboarding/bcc76111-2451-4299-a02d-3f067cf3ca5a/"
51	}
52	],
53	"current_steps": [
54	{
55	"slug": "verify_identity",
56	"url": "/v2/onboarding/bcc76111-2451-4299-a02d-3f067cf3ca5a/verify-identity/"
57	}
58	],
59	"metadata": null
60	}

1	javascript
2
3
4	import {Inquiry} from 'react-native-persona';
5	// ...
6	<Button
7	title="Start Inquiry"
8	onPress={() => {
9	Inquiry.fromInquiry('inq_EXAMPLE')
10	.onComplete((inquiryId, status, fields) =>
11	Alert.alert(
12	'Complete',
13	'Inquiry ' + inquiryId + ' completed with status "' + status + '."',
14	),
15	)
16	.onCanceled((inquiryId, sessionToken) =>
17	Alert.alert('Canceled', 'Inquiry ' + inquiryId + ' was cancelled'),
18	)
19	.onError(error => Alert.alert('Error', error.message))
20	.build()
21	.start();
22	}}
23	/>