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 (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 (v1)
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
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
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
- Proof of residence*/residency document, e.g., utility bill, bank statements, etc.
- Translation documents (if submitted documents are not in English)
*Only required if the user's address is not obtainable from the ID/travel cards.
Document upload restrictions:
- File format: PNG, JPEG, PDF
- File size: maximum 8MB per file
- No. of files: maximum 50 files
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:
document_typeallowed values are listed in the Document Types Enumeration (GET /users/enumerations/document_types).kyc_typeallowed values are listed in the KYC Types Enumeration (GET /users/enumerations/kyc_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}}/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 required KYC documents)
{
"count": 1,
"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"
}
],
"status": "pending"
}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.
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
{
"count": 1,
"status": "submitted"
}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",
"program_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
- Submit individual KYC