Who this section is for

Compliance, legal, and engineering leads at businesses building platforms with their own licensed or authorized KYC (and soon KYB) process — 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 pre-verified KYC data directly to PayMongo. 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] --> B[Submit results to PayMongo]
  B --> C{PayMongo validates payload}
  C -->|valid| D[Identity verification passed]
  C -->|invalid| E[Error returned]
  D --> F[Continue to Update and Activate]

📘
Roadmap: Partner Verification will also cover KYB (business risk analysis) for merchant accounts. Today it covers KYC of the authorized representative only.

Eligibility

A platform qualifies for Partner Verification when both are true:

The platform is licensed or authorized to perform KYC — for example, registered with AMLC, or operating under a regulator that permits customer due diligence.
The platform's KYC 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] --> B[2a Partner Verification]
  B -->|skips standard identity verification| C[3 Update account]
  C --> D[4 Activate]

Compared to the standard Quick start, step 2 is replaced. Steps 3 and 4 remain unchanged.

Endpoint

POST /v2/accounts/{account_id}/partner_verification

See the Accounts API reference for the full schema. The endpoint accepts identity documents, a risk profile, optional person and business details, and (for merchants) Ultimate Beneficial Owners.

Prerequisites

🚧
Before you call this endpoint

PayMongo has approved your platform for Partner Verification.

The child account has already been created (POST /v2/accounts) and is in activation_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 refresh.
`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. Only front_image_url is 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

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_status stays pending. Partner Verification does not activate the account.
identity_verification_status is set to passed.
risk_profile.screening_results echoes 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:

Optional — Call Update account to add any remaining person or business details not in the partner payload.
Required — Call Activate account to activate the child and provision capabilities.

Opt-in features — overview of opt-in features.
Quick start — standard onboarding flow that Partner Verification replaces step 2 of.
Appendix — enum values for documents, source of funds, and more.

Who this section is for

What it is

Eligibility

How it fits the flow

Endpoint

Prerequisites

Before you call this endpoint

Authorization

Request payload

Request field reference

Document classification

Response

Error responses

Example errors

Next steps

Related pages