Submit individual KYC
Learn the process of submitting the required information and documentation for individual user identity verification. This guide provides an overview of the Know Your Customer (KYC) requirements needed for verification.
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 KYC endpoints.
Prerequisites
- The individual user profile must already be completed. Refer to the Register customer profile (v2) section for more details.
- The individual user
emailmust have already been verified. - The individual user
mobilemust have already been verified. - The individual user profile must be in an
activestatus.
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
Get KYC
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}}/v2/users/authentications/documents' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'Get KYC response
{
"status": "not_submitted",
"sub_status": "not_submitted",
"documents": null,
"count": 0,
"kyc_details": null
}2
Collect and upload supporting documents
User documents can be collected via the partner's mobile or web app and uploaded via the KYC API.
Document required for upload:
- Front image of the identification/travel card
- Back image of the identification/travel card
- Selfie/full-face image
Document upload restrictions:
- File format: PNG, JPEG, PDF
- File size: maximum 8MB per file
- No. of files: maximum 4 files
Create KYC
Call Create KYC (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.
Create KYC-required field enumerations:
file_typeallowed values are listed in the File Types Enumeration (GET /users/enumerations/file_types).document_typeallowed values are listed in the Document Types Enumeration (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}}.
Create KYC request (upload required KYC documents)
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: ••••••' \
--header 'Authorization: ••••••' \
--form 'file_type="selfie"' \
--form 'document_type="selfie"' \
--form 'file=@"/Users/mm-john/Downloads/1527530326.png"'Create KYC response (upload required KYC documents)
{
"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
}3
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. This invokes the KYC verification process with the MatchMove Compliance team.
Confirm KYC
Call Confirm KYC (PUT /users/authentications/documents) to finalize the uploaded documents and queue the submission for KYC approval.
Confirm KYC request
curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'Confirm KYC 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
}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 (Available for PH region only) | 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 (Available for PH region only) | 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 (Available for PH region only) | 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 (Available for non-PH regions) | KYC Document Verification Update A notification is sent in the event that the KYC status of the user is updated to either approved or rejected | [Approved] No action required. [Rejected] 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": "phdemo",
"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": "phdemo",
"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": ""
}Related Links
On this page
- Submit individual KYC