How to use Persona

Learn how to connect and configure Persona as a KYC provider in B2CORE, including the Persona dashboard setup, connection settings, verification levels, and webhook

This article provides instructions on how to configure B2CORE to use the KYC provider, Persona. With Persona, clients verify their identity in the Persona flow that opens in the B2CORE UI or mobile app: they capture a government ID and a selfie, and Persona checks them. B2CORE receives the result, downloads the document photos to the client's profile, updates the client's data, and approves or declines the verification request.

Before proceeding with the instructions, you must have signed up for Persona and have an active account. Only one Persona connection can exist in B2CORE.

How verification works

A client starts verification for a level that uses Persona. B2CORE creates a Persona inquiry using the inquiry template assigned to this level and pre-fills the client's name, email, and phone number.
The Persona flow opens in the B2CORE UI or mobile app. The client uploads documents and takes a selfie directly in Persona — the files don't pass through B2CORE.
After the client finishes, B2CORE creates a verification request for the level.
Persona decides on the inquiry (automatically with a Persona Workflow, or manually by your compliance team) and sends a webhook to B2CORE.
B2CORE downloads the document photos, updates the client's profile, and approves or declines the request. When the request is approved, the client gets the verification level.

If the client closes the browser or the app before the flow returns to B2CORE, the webhook still finalizes the request, so no data is lost.

Set up Persona

Complete the following steps in the Persona dashboard. You'll need the values you get here to configure the connection in B2CORE.

Create inquiry templates

Create one inquiry template for each B2CORE verification level that must use Persona. Add the verification steps required for the level, such as a government ID and a selfie. Optionally, create a separate template for corporate clients.

Copy the ID of each template (it starts with itmpl_). You can find it in the template settings in the Persona dashboard.

Set up decisioning

Create a Persona Workflow that approves inquiries that pass all checks and declines those that fail. Without it, inquiries stay in the completed or failed status in Persona and never get approved or declined.

If you don't use Persona Workflows, enable the Approve finished checks without a Persona decision option in the B2CORE connection instead. Before you do that, read the warning in Connection settings.

Get the API key

In the Persona dashboard, create an API key. Sandbox keys start with persona_sandbox_, and production keys start with persona_production_. The API URL is the same for both environments; the key defines which environment is used.

Get the environment ID

Copy the ID of the Persona environment that you use (it starts with env_). To find it, in the Persona dashboard, go to Organization > Information.

Create a webhook

In the Persona dashboard, create a webhook with the following settings:

URL: https://{your-B2CORE-back-office-domain}/api/v2/my/verification-persona/webhook
Events:
- inquiry.created
- inquiry.completed
- inquiry.failed
- inquiry.approved
- inquiry.declined
- inquiry.marked-for-review

After you create the webhook, copy its secret (it starts with wbhsec_).

Make sure to replace {your-B2CORE-back-office-domain} with the domain of your B2CORE Back Office, not the B2CORE UI, and without a trailing slash.

How to configure a connection to Persona

Only admins who are assigned the permissions to manage external connections can set up a connection to Persona.

To set up a connection:

In the B2CORE Back Office, navigate to System > External connections.

Click +Create in the upper-right page corner.

On the Create connection page, fill in the following fields:

In the Name field, enter a name that you want to use for the connection.
In the Caption field, enter a caption that will be applied to the connection in the Back Office.
In the Provider dropdown, select Persona.

Click Save to create the connection.

In the connections list, find the Persona connection that you've created and click Edit to enter the connection details.

On the Edit connection page, specify the connection settings.

In the Enabled dropdown, select Yes.

Click Save to apply the settings.

Connection settings

Field	Description	Where to get it
API key	The key that B2CORE uses to call the Persona API. It starts with `persona_sandbox_` or `persona_production_`.	Persona dashboard, API keys. See Get the API key
Webhook secret	The secret used to verify that webhooks come from Persona. It starts with `wbhsec_`.	Persona dashboard, the webhook that you created. See Create a webhook
Environment ID	The ID of the Persona environment. It starts with `env_`. Required.	Persona dashboard. See Get the environment ID
API URL	The Persona API address. Required. The default value is `https://api.withpersona.com`. Keep it for both sandbox and production.	—
Approve finished checks without a Persona decision	Defines what happens when Persona doesn't make a decision. See the details below.	—
Reference ID prefix	A prefix added before the client ID that B2CORE sends to Persona. See the details below.	—
Sync selfies	Defines whether the client's selfie is saved to B2CORE. See the details below.	—

When you edit the connection later, leave the API key and Webhook secret fields empty to keep the saved values.

Approve finished checks without a Persona decision

No (recommended) — B2CORE waits until Persona approves or declines the inquiry.
Yes — an inquiry that the client finished is approved, and an inquiry that failed is declined, without waiting for a Persona decision.

Select Yes only if your Persona dashboard has no Workflow that approves or declines inquiries. Otherwise, requests stay pending forever. Keep in mind that with Yes, anyone who finishes the check is approved, even with a fake document.

Reference ID prefix

Persona treats one reference ID as one person. B2CORE sends the client ID as the reference ID. For example, with the prefix brand-, the client with ID 454 is sent as brand-454.

If several B2CORE installations use the same Persona organization (for example, production and a test stand, or two brands), give each installation a unique prefix. Otherwise, different clients with the same ID are merged into one person in Persona.
If your Persona organization is used only by this B2CORE, leave the field empty. B2CORE then sends the plain client ID.
The prefix can be up to 32 characters long and can contain Latin letters, digits, and the _, ., :, - symbols.

Do not change the prefix after clients have started verification. Those clients would get new persons in Persona.

Sync selfies

Yes (default) — the selfie that the client took in Persona is saved to the client's documents next to the ID photos.
No — only the ID photos are saved. The selfie stays in Persona.

How to create verification levels for Persona

You can create verification levels or modify the existing levels to use Persona for verification.

To create a verification level:

In the B2CORE Back Office, navigate to Verification > Levels.

Click +Create in the upper-right page corner.

On the Create verification level page, fill in the following fields:

In the Index field, specify a non-zero integer value.

The zero (0) index is always assigned to the default verification level. For other verification levels, the index must be greater than zero, such as 1 for Level 1, 2 for Level 2 and so on.
In the Wizard dropdown, select PersonaSDK.
In the Caption field, specify a level name that will be displayed in the B2CORE UI and mobile app, such as Level 1. If required, specify the localization properties for this field by clicking the button located on the right side of the field.
In the Desktop Description field, specify a description of the level to be displayed in the B2CORE UI. This description can include the permissions granted to clients once they obtain this level.

The description for the B2CORE UI can be specified in the HTML format. If required, specify the localization properties for this field.
In the Mobile Description field, specify a level description to be displayed in the mobile app.

The description for the mobile app can be specified in the JSON format. If required, specify the localization properties for this field.
In the Visible dropdown, select Yes.
In the Default dropdown, select No. (Level 0 is always the default verification level).
In the Assigned Client Right dropdown, select a permission level defining the set of permissions that you want to grant to your clients after obtaining this verification level (for details, refer to Client rights).
In the Client tests dropdown, optionally select one or more accreditation tests if you want to force your clients to pass these tests before they can start verification. The list of available tests includes all the tests with visibility set to Yes, which are displayed on the Client tests page.

Click Save to create the level.

After the page reloads, fill in the Persona template fields:

In the Persona inquiry template field, select the inquiry template for this level.
In the Persona inquiry template (corporate clients, empty = same as above) field, optionally select a template for corporate clients. If you leave it empty, corporate clients use the template from the field above.

The fields are displayed as dropdowns with the templates from your Persona account. If the list is unavailable (for example, when you use a sandbox API key), enter the template ID manually. It must start with itmpl_.

The Persona template fields appear only when both conditions are met: the Wizard is set to PersonaSDK, and the Persona connection is enabled. Select the wizard, save the level, and then fill in the template.

Click Save to apply the changes.

Document groups and document types are not required for Persona: the documents that clients must submit are defined in the Persona inquiry template.

Levels that use other wizards keep their current provider.

What happens after verification

Persona sends a webhook to B2CORE when an inquiry changes its status. B2CORE processes the webhook as follows:

Persona event	Result in B2CORE
`inquiry.created`	Logged only
`inquiry.approved`	Documents are saved, the client's data is updated, the request is approved, and the client gets the level
`inquiry.declined`	Documents are saved, and the request is declined. The client can try again
`inquiry.marked-for-review`	Documents are saved, and the request stays pending for a manual decision
`inquiry.completed`, `inquiry.failed`	Documents are saved. The request is approved or declined only if Approve finished checks without a Persona decision is set to Yes

Notes:

B2CORE saves the ID photos and, if Sync selfies is set to Yes, the selfie to the client's documents.
After an approval, B2CORE updates the client's first, middle, and last name, date of birth, country, and address with the data that Persona extracted from the documents. The phone number is not updated.
If a compliance officer makes a decision manually in the Back Office, this decision takes priority over the Persona decision.
Duplicate and out-of-order webhooks are safe: B2CORE always reads the current inquiry state from Persona.
If a webhook is lost, B2CORE re-processes inquiries that have waited for a decision for more than 6 hours (the check runs daily).
Inquiries that the client started but didn't submit don't create verification requests.

B2CORE stores the document expiration date, but it doesn't roll back the level or notify the client when a document expires.

Migrate from SumSub

Configure and enable the Persona connection.
For each level that must use Persona, select the inquiry template, and then change the level's Wizard to PersonaSDK.
Disable the SumSub connection.

Clients keep their current verification levels.

Persona doesn't have an equivalent of SumSub KYT (transaction monitoring). Transaction monitoring via SumSub stops working after you disable the SumSub connection.

Troubleshooting

Requests stay pending after the client finishes verification. Check that a Persona Workflow approves or declines inquiries, or enable Approve finished checks without a Persona decision. Also check that the webhook is created with all the required events.
Webhooks are rejected. Check that the Webhook secret in the connection matches the secret of the webhook in Persona.
The client sees an error when starting verification. Check that the level has an inquiry template selected (for corporate clients, an individual template is used if the corporate one is empty).

How to use Persona

On this page