Project Name

Pipwave eKYC SDK for Javascript

Description

Welcome to the Pipwave eKYC SDK for JavaScript! This readme serves as your comprehensive guide to seamlessly integrate eKYC into your client app. Explore the Pipwave eKYC SDK's structure, delve into its extra features, and smoothly follow the installation process.

Implementing eKYC in your client app is simpler than ever. Just upload identity documents, submit a selfie, and effortlessly retrieve or update verification results.

Upgrading to version 2

Attention users! Please note that the following methods in the SDK have been renamed for better clarity and consistency:

• uploadDoc is now renamed to uploadId
• viewResult is now renamed to viewIdResult
• updateForm is now renamed to updateIdForm

Please update your codebase accordingly to reflect these changes. Thank you for your understanding and cooperation.

Installation

Begin your journey with the Pipwave eKYC SDK using either the Npm or Yarn package manager.

Npm To install the Pipwave eKYC SDK via npm, ensure Node.js is on your system, and execute this command:

 $ npm install pipwave-ekyc-sdk

Yarn To install the SDK with Yarn, execute this command:

 $ yarn add pipwave-ekyc-sdk

Usage

Kickstart your eKYC journey with the Pipwave eKYC SDK by initializing it at the outset of your project. All that's required is your Access Token to get started. Here's how:

import { PWSDK } from "pw-ekyc-web-sdk";

const pwInstance = new PWSDK();
await pwInstance.init(YOUR_ACCESS_TOKEN)

SDK Documentation

Once the Pipwave eKYC SDK is initialized, you can unlock its full potential by making use of its properties and functionalities. The SDK supports 3 vital verification types: Identity Document, Selfie, and Credit Card.

M/O/C:

• M: Mandatory
• C: Required when
• O: Optional

Properties

1. Verification Types

Retrieve the verification types which a user requires to perform eKYC on, by using the following code:

const types = pwInstance.verificationTypes

Output

The result is an array of string with the following possible values:

• national_identity_document
• selfie
• cc
• poa

2. Default Issuing Country

Retrieve the default country using the following code:

const country = pwInstance.defaultCountry

Output

The result is a Country object with the following properties: | Property | Description | |--|--| | iso_code | Country code in ISO2 format. (Example: my, id) | | name | Full name of Country. (Example: Malaysia, Indonesia) |

3. Issuing Country List

Retrieve all issuing countries in ISO2 format:

const issuingCountries = pwInstance.issuingCountries

Output

The result is an array of Country objects. Refer to the Country for more details.

4. Full Country List

Retrieve all countries in ISO2 format:

const countries = pwInstance.countries

Output

The result is an array of Country objects. Refer to the Country for more details.

Methods

1. Upload Identity Document

To upload an identity document, just provide a properly configured UploadIdParam object as an argument to the uploadId() method. Here's how:

const param = {
	front_doc_base64: YOUR_FRONT_DOC;
	back_doc_base64: YOUR_BACK_DOC;
	doc_type: YOUR_DOC_TYPE;
	issuing_country: YOUR_COUNTRY_ISO;
}
const result = await pwInstance.uploadId(param);

UploadIdParam

| Parameter | M/O/C | Description | | --------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | front_doc_uri | C | URI of the cropped front eKYC image, without the background. Required when front_doc_base64 is absent. | | front_doc_uri_full | O | URI of the full front eKYC image, including background. | | back_doc_uri | C | URI of the cropped back eKYC image, without the background. Required when back_doc_base64 is absent. | | back_doc_uri_full | O | URI of the full back eKYC image, including background. | | front_doc_base64 | C | Cropped front eKYC image in base64 format, without the background. Required when front_doc_uri is absent. | | front_doc_base64_full | O | Full front eKYC image in base64 format, including background. | | back_doc_base64 | C | Cropped Back eKYC image in base64 format, without the background. Required when back_doc_uri is absent. | | back_doc_base64_full | O | Full Back eKYC image in base64 format, including background. | | doc_type | M | Type of the document. (Possible values: passport, national_identity_document, driving_license). | | issuing_country | M | ISO2 country code corresponding to the doc_type. For the list of valid options, refer to the default issuing country and issuing country list. |

Output

| Property | Description | | ----------------- | -------------------------------- | | front_document_id | Unique ID of the front document. | | back_document_id | Unique ID of the back document. |

2. Upload Selfie

To upload a selfie, provide a properly configured UploadSelfieParam object as an argument to the uploadSelfie() method:

const param = {
	selfie_base64: YOUR_SELFIE;
	liveness_score: YOUR_LIVENESS_SCORE;
}
const result = await pwInstance.uploadSelfie(param);

UploadSelfieParam

| Parameter | M/O/C | Description | | ------------------ | ----- | ----------------------------------------------------------------------------------------------------------- | | selfie_uri | C | URI of the cropped Selfie eKYC image, without background. Required when selfie_base64 is absent. | | selfie_uri_full | O | URI of the full Selfie eKYC image, including background. | | selfie_base64 | C | Cropped Selfie eKYC image in base64 format, without background. Required when selfie_uri is absent. | | selfie_base64_full | O | Full Selfie eKYC image in base64 format, including background. | | liveness_score | M | Facial liveness detection score. (Sample value: 0.623) |

Output

| Property | Description | | ------------------ | --------------------------------- | | selfie_document_id | Unique ID of the selfie document. |

3. Retrieve Id Verification Results

After completed the Upload Id Verification process, retrieve the id verification results using the viewIdResult() method. No arguments are required for this method:

const result = await pwInstance.viewIdResult();

Output

| Property | Description | | ------------- | -------------------------------------------------------------------------------------------------- | | status | Status of all verification documents. (Possible values: pending, approved, rejected, review) | | is_retriable | Indicates if the verification process can be retried. | | id_status | Status of Identity document verification. (Possible values: pending, approved, rejected, review) | | selfie_status | Status of selfie verification. (Possible values: pending, approved, rejected, review) | | result | (Refer to IdResults) |

IdResults

| Property | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | full_name | Full name captured from the Identity document. | | given_name | Given name captured from the Identity document. | | surname | Surname captured from the Identity document. | | id_number | Identity number captured from the Identity document. | | date_of_birth | Date of birth captured from the Identity document. | | gender | Gender from the Identity document. (Possible values: FEMALE, MALE) | | line1 | First line of the address. | | city | City of the address. | | zip | Zip code of the address. | | state_iso | State/region of the country in ISO2 format. For the available states, please refer to the state/region list. (Example: MY-01) | | country_iso2 | Country code in ISO2 format. For the available countries, please refer to the country list. (Example: my, id) |

4. Update Id Verification Result

After retrieving the id verification results, you can update them using the updateIdForm() method. Pass a properly configured UpdateIdFormParam object to update the results:

const param = {
	full_name: YOUR_FULL_NAME,
	id_number: YOUR_ID_NUMBER,
	date_of_birth: YOUR_DATE_OF_BIRTH,
	address: YOUR_ADDRESS,
	...
};
const result = await pwInstance.updateIdForm(param);

UpdateIdFormParam

| Parameter | M/O/C | Description | | ------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | full_name | C | Full name captured from the Identity document. Required when given_name and surname are absent. | | given_name | C | Given name captured from the Identity document. Required when full_name is absent. | | surname | C | Surname captured from the Identity document. Required when full_name is absent. | | id_number | M | Identity number captured from the Identity document. | | date_of_birth | M | Date of birth captured from the Identity document. | | gender | M | Gender from the Identity document. (Possible values: FEMALE, MALE) | | line1 | M | First line of the address. | | city | M | City of the address. | | zip | M | Zip code of the address. | | state_iso | M | State/region of the country in ISO2 format. For the available states, please refer to the state/region list. (Example: MY-01) | | country_iso2 | M | Country code in ISO2 format. For the available countries, please refer to the country list. (Example: my, id) |

Output

| Property | Description | | -------- | ---------------------------------------------------------------------- | | result | Status of update verification result. (Possible values: true, false) |

5. Retrieve State / Region List

Retrieve the states by passing the country code in ISO2 format as an argument to the fetchStates() method:

const states = await pwInstance.fetchStates(YOUR_COUNTRY_ISO);

Output

| Property | Description | | -------- | -------------------------------------------------------------- | | iso_code | State/region of the country in ISO2 format. (Example: MY-01) | | name | Full name of state. (Example: Selangor, Kuala Lumpur) |

6. Upload Credit card

To upload an credit card, just provide a properly configured UploadCcParam object as an argument to the uploadCc() method. Here's how:

const param = {
	front_doc_base64: YOUR_FRONT_DOC;
	back_doc_base64: YOUR_BACK_DOC;
}
const result = await pwInstance.uploadCc(param);

UploadCcParam

| Parameter | M/O/C | Description | | --------------------- | ----- | ----------------------------------------------------------------------------------------------------------------- | | front_doc_uri | C | URI of the cropped front eKYC image, without the background. Required when front_doc_base64 is absent. | | front_doc_uri_full | O | URI of the full front eKYC image, including background. | | back_doc_uri | C | URI of the cropped back eKYC image, without the background. Required when back_doc_base64 is absent. | | back_doc_uri_full | O | URI of the full back eKYC image, including background. | | front_doc_base64 | C | Cropped front eKYC image in base64 format, without the background. Required when front_doc_uri is absent. | | front_doc_base64_full | O | Full front eKYC image in base64 format, including background. | | back_doc_base64 | C | Cropped Back eKYC image in base64 format, without the background. Required when back_doc_uri is absent. | | back_doc_base64_full | O | Full Back eKYC image in base64 format, including background. |

Output

| Property | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | front_document_id | Unique ID of the front document. | | back_document_id | Unique ID of the back document. | | is_retriable | Indicates if the upload process can be retried. | | is_partially_masked | Indicates if the sensitive info in credit card has been masked. (Example: middle 6 digit number) | | missing_fields | List of the missing fields on credit card. (Possible values: cc_number_first_6, cc_number_last_4, full_name, date_of_expiry) | | masked_coordinates | Coordinates of the masked regions on the document. |

7. Retrieve Credit Card Verification Results

After completing the upload credit card verification process, retrieve the credit card verification results using the viewCcResult() method. No arguments are required for this method:

const result = await pwInstance.viewCcResult();

Output

| Property | Description | | ------------ | ------------------------------------------------------------------------------------------------------ | | status | Status of credit card verification documents. (Possible values: pending, approved, rejected, review) | | is_retriable | Indicates if the verification process can be retried. | | is_expired | Indicates if the card has expired. | | result | (Refer to CcResults). |

CcResults

| Property | Description | | ----------------- | --------------------------------------------------- | | full_name | Full name captured from the credit card. | | cc_number_first_6 | First 6 digits captured from the credit card. | | cc_number_last_4 | Last 4 digits captured from the credit card. | | doe_year | Date of expiry year captured from the credit card. | | doe_month | Date of expiry month captured from the credit card. |

8. Update Credit Card Verification Result

After retrieving the credit card verification results, you can update them using the updateCcForm() method. Pass a properly configured UpdateCcFormParam object to update the results:

const param = {
	full_name: YOUR_FULL_NAME,
	cc_number_first_6: YOUR_CC_FIRST_6_NO,
	cc_number_last_4: YOUR_CC_LAST_4_NO,
	doe_year: YOUR_CC_EXPIRY_YEAR,
	doe_month: YOUR_CC_EXPIRY_MONTH,
 };
const result = await pwInstance.updateCcForm(param);

UpdateCcFormParam

| Parameter | M/O/C | Description | | ----------------- | ----- | --------------------------------------------------- | | full_name | M | Full name captured from the credit card. | | cc_number_first_6 | M | First 6 card number captured from the credit card. | | cc_number_last_4 | M | Last 4 card number captured from the credit card. | | doe_year | M | Date of expiry year captured from the credit card. | | doe_month | M | Date of expiry month captured from the credit card. |

Output

| Property | Description | | -------- | ---------------------------------------------------------------------- | | result | Status of update verification result. (Possible values: true, false) |

9. Upload Proof Of Address

To upload proof of address, just provide a properly configured UploadPoaParam object as an argument to the uploadPoa() method. Here's how:

const param = { poa_base64: YOUR_DOC }
const result = await pwInstance.uploadCc(param);

UploadPoaParam

| Parameter | M/O/C | Description | | ---------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | poa_uri | C | URI of the proof of address document file. Accepted Formats: PNG, JPG, JPEG, or PDF. Size Limit: Maximum file size 2MB. Required when poa_base64 is absent. | | poa_base64 | C | Proof of address document file in base64 format. Accepted Formats: PNG, JPG, JPEG, or PDF. Size Limit: Maximum file size is 2MB. Required when poa_uri is absent. |

Output

| Property | Description | | ------------ | ----------------------------------------------- | | document_id | Unique ID of the document. | | is_retriable | Indicates if the upload process can be retried. |

10. Retrieve Proof Of Address Verification Results

After completing the upload proof of address verification process, retrieve the proof of address verification results using the viewPoaResult() method. No arguments are required for this method:

const result = await pwInstance.viewPoaResult();

Output

| Property | Description | | ------------ | ----------------------------------------------------------------------------------------------------------- | | status | Status of proof of address verification documents. (Possible values: pending, approved, rejected, review) | | is_retriable | Indicates if the verification process can be retried. | | result | (Refer to PoaResults). |

PoaResults

| Property | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | receiver_name | Receiver's full name captured from the document. | | receiver_address | Receiver's first line address. | | receiver_city | City of the receiver's address. | | receiver_zip | Zip code of the receiver's address. | | receiver_state_iso | State/region of the country in ISO2 format. For the available states, please refer to the state/region list. (Example: MY-01) | | receiver_country_iso2 | Country code in ISO2 format. For the available countries, please refer to the country list. (Example: my, id) |

11. Update Proof Of Address Result

After retrieving the proof of address results, you can update them using the updatePoaForm() method. Pass a properly configured UpdatePoaFormParam object to update the results:

const param = {
	receiver_name: RECEIVER_NAME,
	receiver_address: RECEIVER_ADDRESS,
	receiver_city: RECEIVER_CITY,
	...
};
const result = await pwInstance.updatePoaForm(param);

UpdatePoaFormParam

| Parameter | M/O/C | Description | | --------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | receiver_name | M | Receiver's full name captured from the document. | | receiver_address | M | Receiver's first line address captured from the document. | | receiver_city | M | City of the receiver's address captured from the document. | | receiver_zip | M | Zip code of the receiver's address captured from the document. | | receiver_state_iso | M | State/region of the country in ISO2 format. For the available states, please refer to the state/region list. (Example: MY-01) | | receiver_country_iso2 | M | Country code in ISO2 format. For the available countries, please refer to the country list. (Example: my, id) |

Output

| Property | Description | | -------- | ---------------------------------------------------------------------- | | result | Status of update verification result. (Possible values: true, false) |

Acknowledgements

We extend our gratitude to the following open-source projects that greatly contributed to the development of the Pipwave eKYC SDK: webpack, axios, jwt-decode.

Thank you to these remarkable projects and their dedicated teams for making our SDK possible. Your efforts are truly appreciated.