Partner Verification
Determine whether your platform qualifies to use its own KYC and KYB processes for child accounts, and learn how to apply.
Who this section is for
Compliance, legal, and engineering leads at businesses building platforms with their own licensed or authorized KYC and KYB processes — for example, AMLC-registered entities or partners that have completed PayMongo's process review. Partner Verification lets your platform reuse its existing verification work instead of running users through PayMongo's identity verification.
What it is
Partner Verification is an opt-in capability that lets approved partners submit their own verification results directly to PayMongo. What you submit depends on the account type:
| Account type | What you submit |
|---|---|
consumer | KYC of the account holder. |
merchant | KYC of the authorized representative and KYB, the business due diligence (business details and UBOs). |
For a merchant, KYC and KYB are submitted together in one request. One without the other is rejected. The Accounts API skips its identity verification step and accepts your verification result as evidence. The child account moves to identity_verification_status: "passed" and is ready for Update and Activate.
flowchart LR
A[Partner runs own KYC<br/>plus KYB for merchants] --> B[Submit results to PayMongo]
B --> C{PayMongo validates payload}
C -->|valid| D[Partner result accepted as passed]
C -->|invalid| E[Error returned]
D --> F[Update and Activate]
F -.->|async, after activation| G[PayMongo Risk Engine assessment]
PayMongo still runs its own risk assessmentPayMongo does not run its own identity verification on these accounts; it accepts your passed result. It still runs its own minimum risk assessment, based on PayMongo's own rules: on activation, all account details go through PayMongo's Risk Engine asynchronously. Parent accounts do not have access to this assessment or its results.
Eligibility
A platform qualifies for Partner Verification when both are true:
- The platform is licensed or authorized to perform KYC (and KYB, if it onboards merchants) — for example, registered with AMLC, or operating under a regulator that permits customer due diligence.
- The platform's KYC process (and, for merchants, KYB process) has been reviewed and approved by PayMongo's Risk and Compliance team against PayMongo's required standards.
Email [email protected] to start a process review.
How it fits the flow
flowchart LR A[1 Create account] --> W[2 Register child webhook] W --> B[3a Partner Verification] B -->|skips standard identity verification| C[4 Update account] C --> D[5 Activate]
Compared to the standard Quick start, step 3 is replaced. Steps 4 and 5 remain unchanged.
Endpoint
POST /v2/accounts/{account_id}/partner_verificationSee the Accounts API reference for the full schema. The endpoint accepts identity documents, a risk profile, and optional person details for every account, plus business details and Ultimate Beneficial Owners (UBOs), which are required for merchants and not allowed for consumers.
Prerequisites
Before you call this endpoint
- Your account has a registered business type and PayMongo has approved it for linked accounts. Individual accounts can't create child accounts.
- PayMongo has approved your platform for Partner Verification.
- The child account has already been created (
POST /v2/accounts) and is inactivation_status: pending.- You authenticate with the parent's secret key. Only the parent that created the child can submit partner verification for it.
Authorization
Only the parent account can submit Partner Verification for a child account. The authenticated account (identified by the API key) must be the parent that created the child.
Request payload
{
"documents": [
{
"type": "national_id_ph",
"id_number": "<id_number>",
"front_image_url": "https://example.com/front-image.jpg",
"back_image_url": "https://example.com/back-image.jpg",
"metadata": {
"first_name": "<first_name>",
"last_name": "<last_name>",
"date_of_birth": "<date_of_birth>"
}
},
{
"type": "selfie",
"front_image_url": "https://example.com/selfie.jpg"
}
],
"risk_profile": {
"screening_results": {
"un_sanctions": false,
"ofac_sanctions": false,
"pep_connected": false,
"adverse_news": false,
"foreign_owned": false
},
"verification": {
"source": "<partner_name>",
"partner_verification_id": "<partner_verification_id>",
"verified_at": "2026-05-12T12:00:00Z",
"next_verification_refresh_schedule": "2027-05-12T12:00:00Z"
}
},
"person": {
"first_name": "<first_name>",
"last_name": "<last_name>",
"mobile_number": "<mobile_number>",
"email_address": "<email_address>",
"date_of_birth": { "day": "<day>", "month": "<month>", "year": "<year>" },
"nationality": "PHL",
"nature_of_work": "employed_locally",
"place_of_birth": { "city": "<city>", "country": "PH" },
"source_of_funds": "salary",
"source_of_funds_salary": "<employer_name>",
"address": {
"line1": "<street_address>",
"city": "<city>",
"state": "PH-MNL",
"postal_code": "<postal_code>",
"country": "PH"
}
},
"business": {
"trade_name": "<business_trade_name>",
"description": "<business_description>",
"industry": "5999",
"age": 5,
"size": "between_10_and_50",
"physical_store": true,
"estimated_monthly_volume": "between_1M_and_3M",
"tin": "<business_tin>",
"dti_registered_name": "<dti_name>",
"address": {
"line1": "<street_address>",
"city": "<city>",
"state": "PH-MNL",
"postal_code": "<postal_code>",
"country": "PH"
}
},
"ubos": [
{
"first_name": "<first_name>",
"last_name": "<last_name>",
"middle_name": "<middle_name>",
"date_of_birth": { "day": "<day>", "month": "<month>", "year": "<year>" },
"nationality": "PHL",
"ownership_percentage": 100.0,
"phone_number": "+63912345678",
"email_address": "<email_address>",
"tax_id": "<ubo_tin>",
"address": {
"line1": "<street_address>",
"city": "<city>",
"state": "PH-MNL",
"postal_code": "<postal_code>",
"country": "PH"
}
}
]
}Request field reference
| Field | Type | Required | Description |
|---|---|---|---|
documents | array | Yes | Identity documents and selfie. Minimum 1 document, exactly 1 selfie. Each document type must be unique. See Document classification. |
documents[].type | string | Yes | Document type. For ID documents: see the Appendix. For liveness check: selfie (exactly 1 required). |
documents[].id_number | string | Conditional | Required for ID document types. Not used for selfie. |
documents[].front_image_url | string | Yes | HTTPS URL to the front image (for ID documents) or selfie. Required for all document types including selfie. |
documents[].back_image_url | string | Conditional | Required for national_id_ph, driving_license_ph, alien_registration_card_ph, other_passport. Optional for other ID types. Not used for selfie. |
documents[].metadata | object | Conditional | Required for ID document types. Must contain ≥1 non-empty key-value pair (for example, {"first_name": "John"}). Not used for selfie. |
risk_profile | object | Yes | Risk profile data from your KYC process. |
risk_profile.screening_results | object | Yes | Sanctions and screening check results. |
risk_profile.screening_results.un_sanctions | boolean | Yes | Customer appears on UN sanctions list. |
risk_profile.screening_results.ofac_sanctions | boolean | Yes | Customer appears on OFAC sanctions list. |
risk_profile.screening_results.pep_connected | boolean | Yes | Customer has Politically Exposed Person (PEP) connections. |
risk_profile.screening_results.adverse_news | boolean | Yes | Customer has adverse news or negative media. |
risk_profile.screening_results.foreign_owned | boolean | Yes | Customer is a foreign-owned entity. |
risk_profile.verification | object | Yes | Verification metadata. |
risk_profile.verification.source | string | Optional | Name of your KYC partner or process. |
risk_profile.verification.partner_verification_id | string | Yes | Your internal verification ID, used for audit trail. |
risk_profile.verification.verified_at | string | Yes | ISO 8601 datetime when verification completed. Must not be in the future. |
risk_profile.verification.next_verification_refresh_schedule | string | Yes | ISO 8601 datetime for the next scheduled KYC or KYB refresh. See Recommended refresh schedule. |
person | object | Optional | Account holder's personal information. Recommended to populate. |
business | object | Conditional | Required for merchant accounts. Not allowed for consumer accounts. |
ubos | array | Conditional | Required for merchant accounts (minimum 1 UBO). Not allowed for consumer accounts. |
Person, business, and UBO field details follow the same conventions as Update account. For enum values, see the Appendix.
Document classification
Selfie (liveness check):
selfie— exactly one required. Onlyfront_image_urlis used.
Primary IDs — 1 primary required, OR 2+ secondary required:
alien_registration_card_ph,driving_license_ph,firearm_license_ph,national_id_ph,other_passport,passport,prc_id_ph,sssid_ph,umid_ph
Secondary IDs — required only if no primary is present (2+ needed):
barangay_clearance_ph,nbi_clearance_ph,pag_ibig_ph,philhealth_ph,police_clearance_ph,postal_id_ph,tin_id,voter_id_ph
Beneficial ownership declaration
beneficial_ownership_declaration— for corporations and One Person Corporations. Optional on this endpoint. The payouts of a corporation or One Person Corporation activated without it are held until PayMongo verifies it.
Validation rules
| Result | Combination |
|---|---|
| Accepted | 1+ primary, any secondaries, exactly 1 selfie |
| Accepted | 0 primary, 2+ secondaries, exactly 1 selfie |
| Rejected | 0 primary and only 1 secondary |
| Rejected | 0 selfies or 2+ selfies |
| Rejected | Duplicate document types in the same request |
Response
{
"data": {
"id": "org_d395d43f9a81a3d97f3e250f",
"type": "consumer",
"activation_status": "pending",
"person": {
"type": "representative",
"first_name": "John",
"last_name": "Doe",
"mobile_number": "09991234567",
"email_address": "[email protected]",
"date_of_birth": { "day": 15, "month": 1, "year": 1990 },
"nationality": "PHL",
"nature_of_work": "employed_locally",
"place_of_birth": { "city": "Manila", "country": "PH" },
"source_of_funds": "salary",
"source_of_funds_salary": "ABC Corporation",
"address": {
"line1": "123 Main Street",
"city": "Manila",
"state": "PH-MNL",
"postal_code": "1000",
"country": "PH"
},
"identity_verification_status": "passed"
},
"risk_profile": {
"screening_results": {
"un_sanctions": false,
"ofac_sanctions": false,
"pep_connected": false,
"adverse_news": false,
"foreign_owned": false
}
},
"created_at": 1778575949,
"updated_at": 1778575949
}
}Response notes
activation_statusstayspending. Partner Verification does not activate the account.identity_verification_statusis set topassed.risk_profile.screening_resultsechoes the request.
Error responses
| HTTP | Code | When |
|---|---|---|
| 400 | parameter_required | A required field is missing. |
| 400 | parameter_invalid | A field fails validation (format, enum, future date, document URL, empty metadata). |
| 401 | authentication_failed | Invalid or missing API key. |
| 403 | forbidden | Caller is not the parent that created the child. |
| 403 | partner_kyc_reliance_not_eligible | The parent has not been approved for Partner Verification. |
| 404 | not_found | The account_id does not exist. |
| 502 | internal_server_error | Upstream Files, Verifications, or other internal service error. |
Example errors
{
"errors": [
{
"code": "parameter_invalid",
"detail": "documents[0].back_image_url is required for document type 'national_id_ph'.",
"source": { "pointer": "documents[0].back_image_url" }
}
]
}{
"errors": [
{
"code": "parameter_invalid",
"detail": "Must have at least 1 primary ID document, or at least 2 secondary ID documents.",
"source": { "pointer": "documents" }
}
]
}{
"errors": [
{
"code": "parameter_required",
"detail": "adverse_news is required.",
"source": { "pointer": "risk_profile.screening_results.adverse_news" }
}
]
}Next steps
After Partner Verification succeeds:
- Required for Philippine merchant accounts, else optional — Call Update account to send
declared_min_price_amount,declared_max_price_amount,declared_price_currencyandaddress_type, which Partner Verification does not take, and any remaining person or business details. Until all four are set, Activate refuses a merchant account whose country of registration isPHor not set, withparameter_required. When that account's business type isindividualor not set, Activate also needsregistration_intent. This applies to accounts activated on or after November 27, 2026. Until December 31, 2026, a fully managed linked account can be activated without these fields. - Required — Call Activate account to activate the child and provision capabilities.
Keeping due diligence up to date
Approval is not a one-time step. Under PayMongo's policies, you are responsible for keeping each account's KYC and KYB up to date after onboarding.
Recommended refresh schedule
Refresh the due diligence of every account you verified, and submit the updated data, on the schedule recommended for its risk level:
| Risk level | Recommended refresh |
|---|---|
| Low | Every 36 months |
| Medium | Every 24 months |
| High | Every 12 months |
This is why the request asks for risk_profile.verification.next_verification_refresh_schedule: it records when the next refresh is due.
Re-KYC and Re-KYB
PayMongo may ask you to reprocess an account, with a Re-KYC or Re-KYB for enhanced due diligence, outside the refresh schedule. This ad hoc review can be triggered when:
- A periodic risk review shows the account's risk level has increased.
- The account is flagged by anti-money laundering monitoring.
- The account is flagged for suspected fraud.
- Negative news or findings about the account come to light.
- Regular screening matches the account against a watchlist or negative database.
- The account starts using a new PayMongo product or service.
Submitted by email for nowThere is no API for refreshes or Re-KYC and Re-KYB yet. Send refreshed due diligence, and respond to Re-KYC or Re-KYB requests, by email to [email protected]. A dedicated flow, API, and webhooks are coming in H1 2027.
Possible consequences
If a refresh is overdue, a Re-KYC or Re-KYB request goes unanswered, or the findings raise concerns, PayMongo may restrict the account. Depending on the severity of the findings, this can include:
- Putting the account's payouts on hold.
- Freezing the account's wallet.
- Disabling the account.
Related pages
- Opt-in features — overview of opt-in features.
- Quick start — standard onboarding flow that Partner Verification replaces step 3 of.
- Appendix — enum values for documents, source of funds, and more.
Updated 4 days ago
