[PH] Authentication-based verification
Explore the steps required to submit information for an authentication-based individual user identity verification. This document provides a clear overview of the specific Know Your Customer (KYC) requirements tied to this verification mode. Use this guide to easily navigate the requirements and complete the authentication-based verification process.
Note:
Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process.
Use Cases
- You want to do authentication-based verification using PH National ID eVerify through the Banking Partner integration.
- You want to submit supporting documents that will help in the individual user identity verification in the platform.
- You want to add a feature to your application that will enable individual users to upload supporting documents through the MatchMove KYC endpoints and do authentication-based verification using PH National ID eVerify with the Banking Partner integration.
Prerequisites
- The individual user profile must be created. Refer to the Register customer profile (v2) section for more details.
- You have implemented the Banking Partner's PH National ID eVerify integration and have access to the eVerify Identifiers (discussed in step 4. Confirm all uploads and submit KYC for approval).
API Workflow (v2)
1
Check if an individual user is allowed to submit KYC
Before allowing a user to submit their KYC documents, we must first verify their current KYC status. This means that if the user's KYC status is not listed below, the entry point or screen for initiating KYC submission must 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 verificationrejected- the user can now resubmit because their previous KYC submission was rejected during verification
List KYC Documents
Call List KYC Documents (GET /users/authentications/documents) to retrieve the KYC status of an individual user.
List KYC Documents request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'
List KYC Documents response
{
"status": "not_submitted",
"sub_status": "not_submitted",
"documents": null,
"count": 0,
"kyc_details": null
}
*To ensure data security, all document URLs provided in the response are time-sensitive and will expire within 5 minutes. Subsequent access beyond this timeframe will require you to generate or refresh the links.
2
(Optional) Request a verification session before document upload
Note:
This step is only required for programs with multiple KYC methods enabled (e.g., document-based and authentication-based). If your program has only one active method, you may skip this step.
Every document-based KYC process begins by requesting a new verification session for the newly onboarded user. This step assigns a unique KYC verification session ID to manage their onboarding workflow. This session ID is strictly required before you can proceed with uploading any of the user's identity documents.
Before requesting a KYC verification session, you must first check the id_type submitted by the user. This value determines the specific verification mode required for their KYC process.
Get Individual Users
Call Get Individual Users (GET /users/{{user_id}}) passing in the user ID of the user to retrieve his user profile.
Get Individual Users request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/{{user_id}}' \
--header 'Authorization: ••••••'
Get Individual Users response
{
"addresses": {
"billing": {
"city": "MARIKINA_CITY_NCR",
"country": "PHL",
"line_1": "150 Sunshine Street",
"line_2": "Santa Elena (Pob.)",
"line_3": "SANTA_ELENA",
"line_4": "NCR",
"postal_code": "1800",
"state": "NCR"
},
"identity_verification": {},
"residential": {
"city": "MAKATI_CITY_NCR",
"country": "PHL",
"line_1": "50 Makati Avenue",
"line_2": "Bangkal",
"line_3": "BANGKAL",
"line_4": "NCR",
"postal_code": "1228",
"state": "NCR"
},
"shipping": {}
},
"agent_id": "",
"annual_income_range": "",
"birth": {
"city": "MAKATI_CITY_NCR",
"country": "PHL",
"date": "1991-11-11",
"line_1": "50 Makati Avenue",
"line_2": "Bangkal",
"line_3": "BANGKAL",
"line_4": "NCR",
"state": "NCR"
},
"client_ref_id": "23123213",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2026-08-12T11:02:29Z",
"date_updated": "2026-08-18T18:11:05Z",
"email": "john.smith@matchmove.com",
"employment_details": {
"business_address": {
"city": "MAKATI_CITY_NCR",
"country": "PHL",
"line_1": "50 Makati Avenue",
"line_2": "Bangkal",
"line_3": "BANGKAL",
"line_4": "NCR",
"postal_code": "1228",
"state": "NCR"
},
"business_purpose": "",
"business_trading_name": "",
"expected_monthly_revenue": "",
"industry": "",
"industry_key": "",
"own_economic_interest_signed_at": "",
"vat_number": ""
},
"employment_type": "EMPLOYED_REGULAR",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {},
"first_name": "John",
"gender": "MALE",
"id": "{{user_id}}",
"identification": {
"primary": {
"id_issuance_country": "PHL",
"id_number": "D312312312312",
"id_type": "NATIONAL_ID"
},
"secondary": {}
},
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "UNKNOWN",
"job_title": "",
"kyc_processed_date": "2026-08-12T03:02:34Z",
"kyc_status": "completed",
"kyc_sub_status": "approved",
"last_name": "Smith",
"main_income_source": "PAYROLL",
"marital_status": "",
"metadata": null,
"middle_name": "",
"mobile": "9123812845",
"mobile_country_code": "63",
"mothers_details": {
"maiden_name": "Juana Williams"
},
"nationality": "PHL",
"partner_id": "",
"pending_update": [],
"preferred_name": "John Smith",
"provider_account_number": "17865033123122312",
"provider_ref_id": "31312312310375312312",
"purpose_of_account_opening": "",
"requirements": {
"eventually_due": {
"required_actions": [],
"required_attributes": [],
"required_documents": []
},
"immediately_due": {
"required_actions": [],
"required_attributes": [],
"required_documents": []
},
"pending_verification": {}
},
"residency_country": "",
"risk_assesment_status": "UNKNOWN",
"risk_evaluation_date": null,
"salutation": "",
"self_declared_as_pep": false,
"socioprofessional_category": "",
"status": "active",
"status_message": "",
"status_reason_code": "",
"sub_status": "active",
"suffix": "",
"title": "",
"tos_acceptance": {
"date": "0001-01-01T00:00:00Z",
"device_id": "",
"ip": "",
"service_agreement": "",
"user_agent": ""
},
"transaction_status": "",
"transaction_sub_status": "",
"type": "customer",
"verification_expiry": null,
"work_country": ""
}
Follow the appropriate flow below based on the submitted id_type:
Document-based verification
All supported proof of identification documents, such as id_type = PASSPORT, UMID, DRIVERS_ID, etc., including NATIONAL_ID can be forwarded for document-based KYC verification.
Proceed to the Document-based Verification section and follow the document-based KYC verification steps.
Authentication-based verification (Optional)
Programs enabled for authentication-based verification can offer an additional workflow: users submitting id_type = NATIONAL_ID can be forwarded for authentication-based KYC.
Proceed to request the Initiate KYC Submission step below.
Initiate the authentication_based verification by requesting a KYC verification session:
Initiate KYC Submission
Call Initiate KYC Submission (POST /users/authentications/documents/verifications) passing authentication_based in the verification_mode parameter to receive a new KYC verification session ID.
Initiate KYC Submission request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"verification_mode":"authentication_based"
}'
Initiate KYC Submission response
{
"created_date": "2026-08-12T10:17:44+0800",
"id": "d35029a9579e4cc0b2c09ce1a44681d5",
"requirements": {
"eventually_due": {
"required_actions": [
"confirm_submission"
],
"required_attributes": [],
"required_documents": []
},
"immediately_due": {
"required_actions": [],
"required_attributes": [],
"required_documents": [
"selfie"
]
},
"pending_verification": {
"confirm_submission": {
"attributes": [
"authentication.identifier",
"authentication.reference_number",
"authentication.processed_date"
],
"link": {
"href": "/{{program_code}}/v2/users/authentications/documents",
"method": "PUT"
},
"verification_id": "vfc_eb4722c70eae4e5d82e430f1d5743a67"
}
}
},
"sub_type": "customer",
"type": "users",
"verification_id": "vfc_eb4722c70eae4e5d82e430f1d5743a67",
"verification_mode": "authentication_based"
}
Understanding the Initiate KYC Submission response
The API returns the following information:
verification_id | Unique identifier for the verification session that will track all the verification activities that the user will undergo. |
|---|---|
verification_mode | The verification mode that was selected for the verification session. |
requirements | Defines the documents, attributes, and actions required to complete the verification flow. Clients should always follow the returned requirements instead of assuming the next verification step. |
Requirements for KYC Verification
The Initiate KYC Submission API returns a requirements object that describes the information and actions needed to complete verification. Simply follow these requirements to ensure a smooth and accurate onboarding flow.
| Lists the document types that must be uploaded before the verification can proceed. | Upload the required documents using Upload KYC Documents ( |
| Lists the actions that should be completed after all immediate requirements have been satisfied. | Once you've fulfilled all immediate requirements, perform these listed actions in sequential order. |
| Includes further actions that unlock once an asynchronous verification begins. Each action supplies the verification ID, any necessary attributes, and the API endpoint needed to take the next step. | Keep an eye on the verification status. If this object contains data, perform the specified action using the API details provided. |
Pending Verification
Each action returned under pending_verification contains the following fields:
| The verification session associated with the pending action. |
| List of attributes required to complete the action. This field is returned only when additional information is required. |
| HTTP method to invoke. |
| API endpoint to invoke for completing the action. |
Initiate KYC Submission - Requirements payload example
{
"requirements": {
"immediately_due": {
"required_documents": [
"selfie"
],
"required_attributes": [
"first_name",
"last_name"
],
"required_actions": [
"email_verification",
"mobile_verification"
]
},
"eventually_due": {
"required_actions": [
"confirm_submission"
]
},
"pending_verification": {
"confirm_submission": {
"verification_id": "ver_987654321",
"attributes": [
"authentication.identifier",
"authentication.reference_number",
"authentication.processed_date"
],
"link": {
"method": "PUT",
"href": "{domain}/{product_code}/v2/users/authentications/documents"
}
}
}
}
}
3
Collect and upload supporting documents (requirements.immediately_due.required_documents)
Review the user.requirements object and check the requirements.immediately_due.required_documents list to identify exactly which supporting documents are needed from the user. You can seamlessly collect these required files directly through your own mobile or web application. Once collected, securely upload each document to our system using the Upload KYC Documents API.
You will not be able to proceed to upload any document unless therequirements.immediately_due.required_attributes and therequirements.immediately_due.required_actionsrequirements are satisfied. You will encounter an error requesting the required missing information and actions to be completed before any document upload.
Document upload restrictions:
- File format: PNG, JPEG, PDF
- File size: maximum 8MB per file
- No. of files: maximum 4 files
Upload KYC Documents
Call Upload KYC Documents (POST /users/authentications/documents) to upload KYC documents. This method only allows for the upload of a single document. For multiple documents, this API should be called for each document upload.
Upload KYC Documents-required field enumerations:
file_typeallowed values are listed in the List File Types Enumerations (GET /users/enumerations/file_types).document_typeallowed values are listed in the List Document Types Enumerations (GET /users/enumerations/document_types).
*These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}}.
Upload KYC Documents request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--form 'file_type="selfie"' \
--form 'document_type="selfie"' \
--form 'file=@"/Users/mm-john/Downloads/1527530326.png"'
Upload KYC Documents response
{
"verification_id": "vfc_4852f08291c2495f87d2f04575dd8441",
"status": "pending",
"sub_status": "pending_document_submission",
"documents": [
{
"date": {
"created": "2025-09-29T12:01:38+0800"
},
"id": "33MENFBXQB6BPzEeBTMGul5yk5U",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/selfie/download/33MENFBXQB6BPzEeBTMGul5yk5U.png",
"provider_document_id": "",
"status": "uploaded",
"type": "selfie"
}
],
"count": 1,
"kyc_details": null
}
(Optional) Delete erroneous, incorrect, or rejected (resubmission) KYC documents
Delete KYC Documents
Call Delete KYC Documents (DELETE /users/authentications/documents/{{document_id}}) to delete existing or submitted documents of a user.
Delete KYC Documents request
curl --location --request DELETE 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/{{document_id}}' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'
Delete KYC Documents response
{
"success": true
}
4
Confirm all uploads and submit KYC for approval
Once all the required documents have been uploaded, the partner must confirm and finalize KYC for submission. Once the application is finalized, the KYC verification process will commence.
Confirm KYC Submission
Call Confirm KYC Submission (PUT /users/authentications/documents/verifications) passing the PH National ID eVerify identifiers to finalize the uploaded documents and queue the submission for KYC approval.
The following three fields are populated directly from your direct integration with the Banking Partner's eVerify API.
You must capture and map these specific data points as parameters and pass it to the Confirm KYC.
These will allow MatchMove and the Banking Partner to be able to map and verify the eVerify results, and update the MatchMove platform accordingly.
| Document ID used for authentication |
|---|---|
| eVerify reference number |
| eVerify processed date |
Confirm KYC Submission request
curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents/verifications' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••' \
--header 'Content-Type: application/json' \
--data-raw '{
"authentication": {
"identifier": "{{document_id}}",
"reference_number": "{{everify_reference_no}}",
"processed_date": "{{everify_date}}"
}
}'
Confirm KYC Submission response
{
"verification_id": "vfc_4852f08291c2495f87d2f04575dd8441",
"status": "in_progress",
"sub_status": "submitted",
"documents": [
{
"date": {
"created": "2025-09-29T12:01:38+0800"
},
"id": "33MENFBXQB6BPzEeBTMGul5yk5U",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/selfie/download/33MENFBXQB6BPzEeBTMGul5yk5U.png",
"provider_document_id": "",
"status": "uploaded",
"type": "selfie"
},
{
"date": {
"created": "2025-09-29T12:05:55+0800"
},
"id": "33MEtad0IwFBakKiY7DWr9Yrxv6",
"id_type": "NATIONAL_ID",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/id/download/33MEtad0IwFBakKiY7DWr9Yrxv6.png",
"provider_document_id": "",
"side": "front",
"status": "uploaded",
"type": "id"
},
{
"date": {
"created": "2025-09-29T12:06:08+0800"
},
"id": "33MEvAu1cKjbp9IZbYDXJVYdikG",
"id_type": "NATIONAL_ID",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/id/download/33MEvAu1cKjbp9IZbYDXJVYdikG.png",
"provider_document_id": "",
"side": "back",
"status": "uploaded",
"type": "id"
}
],
"count": 3,
"kyc_details": null
}
In the live environment, this KYC submission will go through a series of automated verifications and, depending on the user profile risk, may require a manual verification.
In the staging environment, this KYC verification process can be simulated by sending additional simulation parameters. Refer to the Simulate individual KYC section to learn more.
5
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.
USER.DOCUMENT_VERIFICATION.STATUS | KYC Document Verification Update |
|
Deprecation notice: | 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. |
Deprecation notice: | KYC Verification Approved A notification is sent in the event that the KYC status of the user is updated to approved | No action required. |
Deprecation notice: | 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. |
USER.DOCUMENT_VERIFICATION.STATUS sample webhook payload (pending activation)
{
"program_code": "{{program_code}}",
"webhook_event": "USER.DOCUMENT_VERIFICATION.STATUS",
"entity_type": "USER",
"version": "v2",
"event_timestamp": "2026-08-07 16:30:34+0800",
"message_id": "fc375210-5fa2-422d-8b77-b7eb01690b6e",
"entity_id": "c8e95eb644060eec9b375c96de03a42f",
"entities": {
"user": {
"first_name": "John",
"birth": {
"date": "1990-01-15"
},
"transaction_sub_status": "",
"title": "Mr",
"kyc_status": "in_progress",
"type": "individual",
"tos_acceptance": {
"user_agent": "Web",
"device_id": "",
"date": "0001-01-01T00:00:00Z",
"service_agreement": "",
"ip": ""
},
"gender": "Male",
"last_name": "Smith",
"date_updated": "2026-08-07T16:30:33Z",
"client_ref_id": "497bb3bf-2f93-45d4-acc7-145470c4d4d2",
"mothers_details": {},
"partner_id": "",
"kyc_processed_date": "2026-08-07T16:30:33Z",
"sub_status": "selfie_verification_inprogress",
"verification_expiry": "2026-09-06 00:00:00",
"metadata": {
"key_1": "value_1",
"key_2": "value_2"
},
"email": "john.smith@matchmove.com",
"is_email_verified": "1",
"employment_details": {
"industry_key": "",
"expected_monthly_revenue": "",
"business_trading_name": "",
"own_economic_interest_signed_at": "",
"business_purpose": "",
"industry": "",
"business_address": {},
"vat_number": ""
},
"father_details": {},
"marital_status": "",
"salutation": "",
"status": "pending_activation",
"self_declared_as_pep": false,
"provider_account_number": "",
"main_income_source": "",
"id": "28e7378a801bba5d34910ef3cd3131c3",
"risk_assesment_status": "PENDING",
"mobile_country_code": "63",
"purpose_of_account_opening": "",
"agent_id": "",
"require_provider_update": [],
"pending_update": [],
"addresses": {
"billing": {
"line_2": "Unit 1504",
"state": "Metro Manila",
"line_1": "1847 Mabini Street",
"line_3": "Alder Residences",
"postal_code": "1210",
"country": "Philippines",
"city": "Makati City"
},
"residential": {
"line_1": "1847 Mabini Street",
"line_2": "Unit 1504",
"line_3": "Alder Residences",
"city": "Makati City",
"postal_code": "1210",
"state": "Metro Manila",
"country": "Philippines"
},
"identity_verification": {},
"foundation": {},
"shipping": {},
"operational": {}
},
"kyc_sub_status": "pending_document_submission",
"data_terms_signed_at": "",
"http_status_code": 0,
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"middle_name": "",
"transaction_status": "",
"date_created": "2026-08-07T16:29:21Z",
"is_risk_flagged": "PENDING",
"status_message": "",
"risk_evaluation_date": "0001-01-01T06:55:25Z",
"work_country": "",
"status_reason_code": "",
"identification": {
"secondary": {},
"primary": {
"id_number": "4H7K3856O0",
"metadata": {
"key_1": "value_1",
"key_2": "value_2"
},
"id_type": "Passport",
"id_date_expiry": "2031-03-09",
"id_issuance_country": "Philippines",
"id_date_issued": "2021-03-10"
}
},
"annual_income_range": "",
"nationality": "Nationality for Philippines",
"preferred_name": "John Smith",
"mobile": "9179627560",
"employment_type": "",
"socioprofessional_category": "",
"requirements": {
"pending_verification": {},
"immediately_due": {
"required_actions": [],
"required_attributes": [],
"required_documents": []
},
"eventually_due": {
"required_documents": [],
"required_actions": [],
"required_attributes": []
}
},
"residency_country": "",
"provider_ref_id": "607302535441",
"suffix": "",
"is_mobile_verified": "1",
"verification_id": {},
"fatca_relevant": false,
"job_title": "",
"customer_id": ""
},
"verification_results": {
"details": {},
"verification_id": "vfc_a00ccceca59d363a0b4a631f29165c8e",
"sub_status_code": "PENDING_DOCUMENT_SUBMISSION",
"sub_status": "The documents are pending for submission",
"status": "in_progress"
}
}
}
USER.DOCUMENT_VERIFICATION.STATUS sample webhook payload (rejected)
{
"program_code": "{{program_code}}",
"webhook_event": "USER.DOCUMENT_VERIFICATION.STATUS",
"entity_type": "USER",
"version": "v2",
"event_timestamp": "2026-08-07 16:30:34+0800",
"message_id": "fc375210-5fa2-422d-8b77-b7eb01690b6e",
"entity_id": "c8e95eb644060eec9b375c96de03a42f",
"entities": {
"user": {
"addresses": {
"billing": {
"city": "Quezon City",
"country": "Philippines",
"line_1": "52 Kalayaan Avenue",
"line_2": "Unit 803",
"postal_code": "1100",
"state": "Metro Manila"
},
"foundation": {},
"identity_verification": {},
"operational": {},
"residential": {
"city": "Quezon City",
"country": "Philippines",
"line_1": "52 Kalayaan Avenue",
"line_2": "Unit 803",
"postal_code": "1100",
"state": "Metro Manila"
},
"shipping": {}
},
"agent_id": "",
"annual_income_range": "",
"birth": {
"date": "1992-04-23"
},
"client_ref_id": "ee5e759f-84d2-4d26-85a8-55aeaa27285b",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2026-08-21T09:19:10Z",
"date_updated": "2026-08-21T09:19:11Z",
"email": "john.smith@matchmove.com",
"employment_details": {
"business_address": {},
"business_purpose": "",
"business_trading_name": "",
"expected_monthly_revenue": "",
"industry": "",
"industry_key": "",
"own_economic_interest_signed_at": "",
"vat_number": ""
},
"employment_type": "",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {},
"first_name": "John",
"gender": "Male",
"http_status_code": 0,
"id": "9ae592f1bc5a6c43be33141566c299ed",
"identification": {
"primary": {
"id_date_expiry": "2030-11-01",
"id_date_issued": "2020-11-02",
"id_issuance_country": "Philippines",
"id_number": "HB45697856113",
"id_type": "Id Card",
"metadata": {
"key_1": "value_1",
"key_2": "value_2"
}
},
"secondary": {}
},
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "PENDING",
"job_title": "",
"kyc_processed_date": "2026-09-30T09:52:11Z",
"kyc_status": "completed",
"kyc_sub_status": "rejected",
"last_name": "Smith",
"main_income_source": "",
"marital_status": "",
"metadata": {
"key_1": "value_1",
"key_2": "value_2"
},
"middle_name": "",
"mobile": "9811321893",
"mobile_country_code": "63",
"mothers_details": {},
"nationality": "Nationality for Philippines",
"partner_id": "",
"pending_update": [],
"preferred_name": "John Smith",
"provider_account_number": "",
"provider_ref_id": "8fad3f391897a24dbc5747567",
"purpose_of_account_opening": "",
"require_provider_update": [],
"requirements": {
"eventually_due": {
"required_actions": [],
"required_attributes": [],
"required_documents": []
},
"immediately_due": {
"required_actions": [
"cdd_verification"
],
"required_attributes": [],
"required_documents": []
},
"pending_verification": {}
},
"residency_country": "",
"residency_status": "",
"risk_assesment_status": "PENDING",
"risk_evaluation_date": "0001-01-01T06:55:25Z",
"salutation": "",
"self_declared_as_pep": false,
"socioprofessional_category": "",
"status": "pending_activation",
"status_message": "",
"status_reason_code": "",
"sub_status": "document_verification_failed",
"suffix": "",
"supporting_documents": [
{
"id_issuance_country": "Philippines",
"id_type": "Utility Bill"
}
],
"title": "Mr",
"tos_acceptance": {
"date": "0001-01-01T00:00:00Z",
"device_id": "",
"ip": "",
"service_agreement": "",
"user_agent": "Web"
},
"transaction_status": "",
"transaction_sub_status": "",
"type": "individual",
"verification_expiry": "2026-10-30 00:00:00",
"verification_id": {},
"work_country": ""
},
"verification_results": {
"details": {},
"status": "rejected",
"sub_status": "The documents submitted did not meet the criteria",
"sub_status_code": "REJECTED",
"verification_id": "vfc_c3b64581c4debd213d3d69986d3f95ac"
}
}
}
USER.DOCUMENT_VERIFICATION.STATUS sample webhook payload (approved)
{
"program_code": "{{program_code}}",
"webhook_event": "USER.DOCUMENT_VERIFICATION.STATUS",
"entity_type": "USER",
"version": "v2",
"event_timestamp": "2026-08-07 16:30:34+0800",
"message_id": "fc375210-5fa2-422d-8b77-b7eb01690b6e",
"entity_id": "c8e95eb644060eec9b375c96de03a42f",
"entities": {
"user": {
"addresses": {
"billing": {
"city": "Pasig City",
"country": "Philippines",
"line_1": "308 Rizal Avenue",
"line_2": "Barangay Kapitolyo",
"postal_code": "1603",
"state": "Metro Manila"
},
"foundation": {},
"identity_verification": {},
"operational": {},
"residential": {
"city": "Pasig City",
"country": "Philippines",
"line_1": "14 Sampaguita Street",
"line_2": "Barangay Kapitolyo",
"postal_code": "1603",
"state": "Metro Manila"
},
"shipping": {}
},
"agent_id": "",
"annual_income_range": "",
"birth": {
"date": "1988-09-11"
},
"client_ref_id": "1fb1fc02-6c44-410c-b47e-143c488e4a92",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2026-09-30T11:49:08Z",
"date_updated": "2026-09-30T11:58:21Z",
"email": "john.smith@matchmove.com",
"employment_details": {
"business_address": {},
"business_purpose": "",
"business_trading_name": "",
"expected_monthly_revenue": "",
"industry": "",
"industry_key": "",
"own_economic_interest_signed_at": "",
"vat_number": ""
},
"employment_type": "",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {},
"first_name": "John",
"gender": "Male",
"http_status_code": 0,
"id": "a508bd1d7df5290ce2dd7df34d584a1f",
"identification": {
"primary": {
"id_date_expiry": "2029-05-13",
"id_date_issued": "2019-05-14",
"id_issuance_country": "Philippines",
"id_number": "3970584472618",
"id_type": "Id Card",
"metadata": {
"key_1": "value_1",
"key_2": "value_2"
}
},
"secondary": {}
},
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "CLEARED",
"job_title": "",
"kyc_processed_date": "2026-09-30T11:58:21Z",
"kyc_status": "pending",
"kyc_sub_status": "pending_document_submission",
"last_name": "Smith",
"main_income_source": "",
"marital_status": "",
"metadata": {
"key_1": "value_1",
"key_2": "value_2"
},
"middle_name": "",
"mobile": "9427482299",
"mobile_country_code": "63",
"mothers_details": {},
"nationality": "Nationality for Philippines",
"partner_id": "",
"pending_update": [],
"preferred_name": "John Smith",
"provider_account_number": "",
"provider_ref_id": "1a6b6281d9a5b4881556f8ce",
"purpose_of_account_opening": "",
"require_provider_update": [],
"requirements": {
"eventually_due": {
"required_actions": [],
"required_attributes": [],
"required_documents": []
},
"immediately_due": {
"required_actions": [
"cdd_verification"
],
"required_attributes": [],
"required_documents": []
},
"pending_verification": {
"cdd_verification": {
"verification_id": "vfc_409513c31f35aea91726af50433ace64"
}
}
},
"residency_country": "",
"residency_status": "",
"risk_assesment_status": "PENDING",
"risk_evaluation_date": "0001-01-01T06:55:25Z",
"salutation": "",
"self_declared_as_pep": false,
"socioprofessional_category": "",
"status": "pending_activation",
"status_message": "",
"status_reason_code": "",
"sub_status": "aml_verification_inprogress",
"suffix": "",
"supporting_documents": [
{
"id_date_expiry": "2032-02-07",
"id_date_issued": "2022-02-08",
"id_issuance_country": "Philippines",
"id_number": "OHJ76564441Y",
"id_type": "Other"
}
],
"title": "Mr",
"tos_acceptance": {
"date": "0001-01-01T00:00:00Z",
"device_id": "",
"ip": "",
"service_agreement": "",
"user_agent": "Web"
},
"transaction_status": "",
"transaction_sub_status": "",
"type": "individual",
"verification_expiry": "2100-01-30 00:00:00",
"verification_id": {},
"work_country": ""
},
"verification_results": {
"details": {},
"status": "approved",
"sub_status": "Full KYC Verified",
"sub_status_code": "APPROVED",
"verification_id": "vfc_409513c31f35aea91726af50433ace64"
}
}
}
ACCOUNT.KYC.VERIFICATION _<result> sample webhook payload
{
"event_name": "ACCOUNT.KYC.VERIFICATION_REJECTED",
"product_code": "{{program_code}}",
"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": "{{program_code}}",
"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/phdemo/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/phdemo/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/phdemo/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": ""
}
On this page
- [PH] Authentication-based verification