Perform individual eKYC
Learn how to initiate and complete an electronic Know Your Customer (eKYC) check for a user. This guide covers the end-to-end process of using our eKYC solution to verify a customer's identity.
Use Cases
- You want to submit the required KYC documents needed to verify the identity of an individual user.
- You want to submit supporting documents that will help in the individual user identity verification.
- You want to implement a feature in your application that will allow individual users to upload documents using the available MatchMove eKYC Provider.
- You want to implement a feature in your application that will allow individual users to upload supporting documents using the available MatchMove KYC endpoints.
- The individual user will submit KYC by going through the automated eKYC interface to collect selfies and identification documents.
- The individual user will submit KYC through the eKYC interface with an automated approval (no manual intervention required) mechanism.
Prerequisites
- The individual user profile must already be completed. Refer to the Register customer profile (v1) section for more details.
- The individual user profile risk assessment status must not be
risk_flagged. - The individual user profile must be in an
activestatus.
API Workflow
1
Check if an individual user is allowed to submit KYC
Before we allow a user to submit their KYC documents, we first need to check their current KYC status. This means that when the KYC status of the user is not in the list below, the entry point or screen to initiate KYC submission must also be hidden from the partner app interface.
A user can only send a KYC submission for verification if their KYC status is:
- not_submitted - the user has never submitted a KYC for verification
- rejected - the user can now resubmit because their previous KYC submission was rejected during verification
Call Get KYC (GET /users/authentications/documents) to retrieve the KYC status of an individual user.
Get KYC request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'Get KYC response
{
"count": "n/a",
"status": "not_submitted"
}2
Retrieve the eKYC Provider ID from the available services enabled in the program
The availability of eKYC providers will differ from region to region. It will be important to check which one is enabled and configured in your program.
Call Get KYC Providers (GET /oauth/consumer/kyc/providers) to get the eKYC service provider ID (identifier) that is enabled for your program.
Get KYC Provider request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/oauth/consumer/kyc/providers' \
--header 'Authorization: ••••••' Get KYC Provider response
{
"providers": [
{
"id": "pvd_6e4adecc8cc74220a67b8766d879715a",
"name": "Onfido",
"description": "Verifying real identity in a remote world",
"code": "MUAISPONMEJTB12810",
"user_type": "customer",
"callback_url": "https://beta-api.mmvpay.com",
"details": null
},
{
"id": "pvd_927d1da99a8b4b6fae78baebfea73811",
"name": "Matchmove",
"description": "Internal Provider",
"code": "MUAISPCCWEZIS03738",
"user_type": "customer",
"callback_url": "https://beta-api.mmvpay.com",
"details": null
}
]
}jso3
Retrieve the eKYC redirect link to the document collection screen
The eKYC document collection page is a standalone web app. Partners must present the eKYC web app to the customer by rendering it in an in-app or external web browser. Customers can then proceed to perform eKYC by sending their selfie picture and required identity documents.
Call Process KYC Verification (POST /users/authentications/documents/process) by passing the eKYC provider ID to get the href or the redirect link to the eKYC web app.
Process KYC Verification request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents/process' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'provider_id={{ekyc_provider_id}}' \
--data-urlencode 'user_type=customer' \
--data-urlencode 'user_id={{user_id}} \
--data-urlencode 'program_code={{program_code}}' \
--data-urlencode 'mode=web_sdk'curlProcess KYC Verification response
{
"verification_id": "vfc_add3d8e603664df2ac6161ed78d68a8f",
"profile_id": "pfi_2cf00f2a42a04571b73b4bddc06e9ca6",
"success": true,
"links": [
{
"rel": "capture.sdk",
"href": "https://identity.uat.matchmove-beta.com/api/v1/web/sdk?id=7bb523ecc983de217a9deaea2f91c400358f1061e5b4361d0d4b64d6dbbd9a718c531b45492818d29a0a4642e545bb35f2s5adae3791348433175d9dd844de4de81ff951",
"method": "GET"
}
]
}The Process KYC Verification API response will return a capture link that you will need to render and display to an in-app browser (mobile app) or any browser (web app) for your customer.
From here, the customer can perform the KYC document capture and submit their KYC application.
The eKYC verification is asynchronous; some background processing needs to be completed before the approval/rejection can be given. Usually, an automated eKYC verification turnaround time will take instant to a few minutes, provided that all document submissions are clear, legible, and the partner profile aligns perfectly with the document data.
4
Monitor for the approval of the submitted KYC
The KYC verification turnaround time follows an SLA from submission to approval.
If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “KYC Service Advisory” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection.
Go to the Leverage Webhooks section to learn more about setting up the webhooks.
KYC Service Advisory webhooks
Partners have the option to subscribe to the webhook events related to KYC approval.
ACCOUNT.KYC.VERIFICATION_START | KYC Initiate Verification Started A notification is sent in the event that the user completes the eKYC form. | No action required. |
ACCOUNT.KYC.VERIFICATION_COMPLETED | KYC Initiate Verification Success A notification is sent in the event the external eKYC service provider verification process is completed. | No action required. |
ACCOUNT.KYC.VERIFICATION_FAILED | KYC Initiate Verification Failed A notification is sent in the event a failure happens on any process after a verification is completed. | No action required. The verification process will auto-retry. |
ACCOUNT.KYC.VERIFICATION_APPROVED | KYC Verification Approved A notification is sent in the event that the KYC status of the user is updated to approved | No action required. You may now proceed to provision the user with financial products such as accounts and cards. |
ACCOUNT.KYC.VERIFICATION_REJECTED | KYC Verification Rejected A notification is sent in the event that the KYC status of the user is updated to rejected along with a reject code | You may ask the user to retry or redo another round of KYC submission. |
Sample webhook payload
{
"event_name": "ACCOUNT.KYC.VERIFICATION_REJECTED",
"product_code": "sgdemo",
"timestamp": "2025-11-27 17:32:46+0800",
"request_id": "89d69adb-53ff-4e67-9518-db2f8e555a79",
"trace_id": "a2ba30e56005441f97d4ee4be3d53f46_ca91c8763c5b45eb9e51c714351f6388",
"webhook_id": "56b767f6-c0b1-4e2d-8445-01d824d60c97",
"event_data": {
"message_id": "a6c8ad82-1c32-490c-93aa-9db094cfc3a5",
"program_code": "sgdemo",
"status": "pre-kyc",
"timestamp": "2025-11-27 17:32:46+0800",
"retry_counter": 0,
"user": {
"user_hash": "a2ba30e56005441f97d4ee4be3d53f46",
"email": "john.smith@mathcmove.com",
"mobile": "9886689021",
"mobile_country_code": "63",
"status": "rejected",
"sub_status": "account_rejected_by_issuer",
"kyc_status": "completed",
"kyc_sub_status": "rejected",
"transaction_status": "terminated",
"transaction_sub_status": "transaction_blocked_by_issuer",
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "UNKNOWN",
"provider_ref_id": "HMAP251127010416239",
"profile": {
"first_name": "JOHN",
"middle_name": "WILLIAMS",
"last_name": "SMITH",
"preferred_name": "JOHN SMITH",
"gender": "MALE",
"title": "MR",
"nationality": "PHL",
"marital_status": "SINGLE",
"birth": {
"date": "1997-07-17"
},
"email": "john.smith@matchmove.com",
"mobile": "9886689021",
"mobile_country_code": "63",
"addresses": {
"residential": {
"line_1": "5",
"line_2": "Sunny St",
"line_3": ".",
"line_4": "NCR",
"city": "TAGUIG_CITY_NCR",
"state": "NCR",
"country": "PHL",
"postal_code": "1632"
},
"billing": {
"line_1": "5",
"line_2": "Sunny St",
"line_3": ".",
"line_4": "NCR",
"city": "TAGUIG_CITY_NCR",
"state": "NCR",
"country": "PHL",
"postal_code": "1632"
},
"shipping": {},
"identity_verification": {}
},
"employment_details": {
"employment_type": "EMPLOYED_REGULAR",
"business_trading_name": "MatchMove Pay",
"business_address": {
"line_1": "Shaw blvd",
"line_2": "Pasig city",
"line_3": ".",
"line_4": "NCR",
"city": "PASIG_CITY_NCR",
"state": "NCR",
"country": "PHL",
"postal_code": "1632"
}
},
"mothers_details": {
"maiden_name": "Steven"
},
"identification": {
"primary": {
"id_type": "NATIONAL_ID",
"id_number": "3013691154861952",
"id_issuance_country": "PHL",
"id_date_issued": "2025-11-27",
"id_date_expiry": "2027-11-27"
},
"secondary": {}
},
"main_income_source": "OTHERS",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"tos_acceptance": {
"date": "0001-01-01T00:00:00Z",
"ip": "",
"user_agent": "",
"service_agreement": ""
}
}
},
"authentication_documents": {
"count": 3,
"status": "completed",
"sub_status": "rejected",
"failure_reason": "",
"reject_reason_code": [
{
"code": "DOCUMENT_ID_REJECTED",
"description": "The id document submitted is rejected"
}
],
"documents": [
{
"type": "id",
"side": "front",
"id": "363BCiNTxnclrEF2RCaGT19J2Hq",
"id_type": "NATIONAL_ID",
"status": "uploaded",
"link": "https://storage-service.mmvpay.com/api/v1/files/sgdemo/id/download/363BCiNTxnclrEF2RCaGT19J2Hq.jpg",
"provider_document_id": "",
"date": {
"created": "2025-11-27T14:34:08+0800"
}
},
{
"type": "id",
"side": "back",
"id": "363BCzCfZOJnEOEauVrgcBqYcmx",
"id_type": "NATIONAL_ID",
"status": "uploaded",
"link": "https://storage-service.mmvpay.com/api/v1/files/sgdemo/id/download/363BCzCfZOJnEOEauVrgcBqYcmx.jpg",
"provider_document_id": "",
"date": {
"created": "2025-11-27T14:34:10+0800"
}
},
{
"type": "selfie",
"id": "363BD56x5UdHMIvmmTvHn2sERXC",
"status": "uploaded",
"link": "https://storage-service.mmvpay.com/api/v1/files/sgdemo/selfie/download/363BD56x5UdHMIvmmTvHn2sERXC.jpg",
"provider_document_id": "",
"date": {
"created": "2025-11-27T14:34:11+0800"
}
}
]
},
"webhook_event": "ACCOUNT.KYC.VERIFICATION_REJECTED"
},
"provider_response": {
"code": -1,
"message": "FAIL",
"httpCode": null,
"data": null,
"success": false
},
"provider_http_status_code": 200,
"retry_attempt": 0,
"max_retry_attempts": 0,
"max_retry_age": 0,
"message": ""}
}5
Add supplementary documents to the KYC submission
At any stage of the KYC approval and review process, the following can happen:
Pre-KYC Approval
During the KYC review, MatchMove Compliance may request some additional documents on the customer profile that they are reviewing. Specially for high-risk customers who will be required to undergo an Enhanced Due Diligence (EDD) process. Additional documents on top of the standard requirements will be asked to be uploaded for the EDD.
Post-KYC Approval
MatchMove Compliance conducts routine audits on approved KYC profiles to check for document expiry, change of address, etc. These scenarios may require customers to upload up-to-date documents and other supplementary documents to help validate the scenario changes.
To upload the required supplementary documents, the partner will need to use the same document upload API that was used for the KYC submission.
Call Create KYC (POST /users/authentications/documents) to upload supplementary documents.
Create KYC request (upload supplementary documents)
curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'data=<base64_encoded_image> ' \
--data-urlencode 'document_type={{document_type}}' \
--data-urlencode 'kyc_type=MM_DOCUMENT_UPLOAD'Create KYC response (upload supplementary documents)
{
"count": 2,
"documents": [
{
"document_id": "",
"document_type": "selfie",
"kyc_type": "MM_DOCUMENT_UPLOAD",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/30FyROnArptb6UHvTGMc8HVdnh8.jpg"
},
{
"document_id": "",
"document_type": "proof_of_address",
"kyc_type": "MM_DOCUMENT_UPLOAD",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/40CxYOnArptb6UHvTGMc8HVdf0.jpg"
}
],
"status": "pending"
}Related Links
On this page
- Perform individual eKYC