Who this section is for

Engineers and product leads designing the identity verification step. Skim before deciding between the hosted and API-only flows, and come back when handling retries or unexpected failure reasons.

Tips

Default to hosted identity verification unless you already capture images

Hosted identity verification gives you the capture microsite, liveness detection, and document quality checks without extra work on your side. Only use the API-only flow when you have an existing image-capture pipeline (for example, a mobile app that already takes selfies) and you want to avoid the redirect.

Treat identity verification as a step the user can fail

Failure is a normal outcome — lighting, image quality, or document condition trip even careful users. Build your UI to:

• Tell the user clearly that the previous attempt failed.
• Show the failure_reason from the webhook in plain language.
• Offer a "try again" action that creates a new identity verification session.

Make sessions short-lived in your UX

A verification session is valid for 72 hours from creation. In practice, users either complete identity verification within minutes or never come back. Do not link the hosted URL from emails that may be opened days later — generate the session right before the user needs it.

Watch image quality before submitting (API-only flow)

For the API-only flow, validate the basics on your side before posting to PayMongo:

• Image format: JPEG or PNG.
• Image size: large enough that the face takes ~50% of the frame and the document is legible.
• HTTPS-served URLs only. PayMongo does not fetch images over plain HTTP.

Bad images turn into failed results and another round trip for the user.

Use webhooks, not polling

For both hosted and API-only identity verification, the result is delivered as an account.identity_verification.passed or .failed webhook event. Polling Get Account works as a fallback but adds latency and load. Webhooks are the recommended path. See Best practices — Webhooks.

Frequently asked

How long do failed verifications block activation?

They do not. The child account stays in pending activation status, regardless of how many identity verification attempts have failed. Start a new session whenever the user is ready to retry.

Can I switch from hosted identity verification to API-only mid-flow?

Yes. Each verification session is independent. If a hosted session failed or expired, you can start an API-only session next (or vice versa).

What happens to ID images I submit via the API-only flow?

They are stored against the child account for compliance retention. Treat the URLs you provide as one-time-use — PayMongo fetches them at submission, then the originals can be rotated or deleted from your side.

The user passed identity verification but the name does not match what I have in my CRM. What do I do?

The name returned in the account resource is taken from the captured ID. That is the legal name PayMongo will use for compliance. If your CRM holds a different name (preferred name, trading name), keep both — display your CRM name in your UI, send PayMongo's name in compliance reports.

Related

• Quick start — Run identity verification
• Onboarding webhooks — Identity verification
• Partner Verification — bypass identity verification with your own approved process.
• Troubleshooting