Skip to main content

​
Introduction

This documentation provides a detailed explanation of how to integrate with Beans iD Whitelabel API - Hosted. It includes the steps you will go through for integration and provides reference points to the different API endpoints that you will utilise. This implementation allows for a user to verify as a member of any of our supported consumer groups utilising a dedicated whitelabel verification page provided by Pion which is customised to look and feel like your brand.

​
How does it work?

The intended flow is as follows:
1

Authenticate with the Pion API

To conduct a verification, several requests must be made to the Pion API.The Pion API provides an OAuth Client Credentials grant flow which returns an access token. Client credentials can be self-served in the Pion Portal. This will create a new pairing of a clientId and clientSecret that is used to fetch an access token that must be passed into requests that require authentication.Once you’ve got client credentials, you can send a request to the /auth/token endpoint, the documentation for which can be found here.
2

Send a request to the Pion API to start a verification

To begin the verification process a request is sent to the Create Verification endpoint in the Pion API, the documentation for which can be found here.This will begin the verification process for your chosen consumer group, and will create a unique verification ID used to reference this verification going forwards.
The verificationId returned from this step must be saved against your user. This ensures that this verification ID can only be used for the verification of the user it is associated with.
3

Send the user to your dedicated whitelabel verification page, allowing the user to navigate through the UI to complete their verification

Once a verification ID has been generated (detailed in the previous step), a user can be sent into the Beans iD Whitelabel Hosted UI.Simply send your user to the following URL:
  • Replace [verificationId] with the verification ID returned from the Pion API when you created the verification.
  • Replace [redirectUrl] with an encoded URL that the user should be sent to when the verification is complete. For security, this URL will need to be registered against your application via Pion Portal.
4

We’ll send your user back to you and let you know the verification is complete, then you send a request to the Pion API to check the status of the verification

A verification can occur synchronously or asynchronously depending on the method used to verify the user.

​
Synchronous Verifications

Upon a user verifying using a synchronous method within the hosted UI they will be sent to the redirect URL provided.A verificationId parameter will be attached as a query parameter on this URL.
For example: https://example.com/vaas?verificationId=15ab7f14-fc08-445a-a830-84c2f11ef2ef.This verification ID can then be used to fetch the outcome of the verification from the Get Verification Details endpoint, the documentation for which can be found here.
When processing the outcome of a verification, you should ensure the verificationId being used is the verification ID associated with your user. This ensures that the verification result returned belongs to the user being verified, and prevents users from sharing their verification ID.
An event will also be dispatched to a webhook when a verification succeeds. Details about webhook events can be found here.

​
Asynchronous Verifications

When a user is attempting to verify with a synchronous method, they will finish their journey in the hosted UI but their verification will remain in a pending state until it has been reviewed.In this instance, the UI will show a message to the user communicating that their verification is being reviewed.Upon the verification being reviewed there are two possible outcomes:
  • The user is now verified, the verification is successful.
  • The user is not verified, the verification is still pending.
Each of the above will cause a webhook event to be dispatched. The verification ID will be included in the event payload and this should be used to fetch the details of the verification again.Details about webhook events can be found here.When processing a status event:
  • If the verification was successful, you should handle processing this and then notify your user that they are now verified.
  • If the verification is still pending, you should notify the user that they need to try again and direct them back to the hosted UI. Use the same verification ID to construct the link to the UI and the user will be able to attempt to verify again.
5

Depending on the result of the verification, you should either

a) Successful resultUse the verification id + Beans iD to provision the users account with the consumer group verification status, and enable that user to obtain the offering that you would like to provide them. Don’t forget to manage the communication to the user to make sure they activate and make use of the offering you are making available.b) Unsuccessful resultIn an unfortunate event when a user is met with an unsuccessful result of verification, you should communicate to the user that this is the case and look to give them the option to verify their consumer group status again.