Key concepts
Walk away with a clear mental model of parent and child accounts, the lifecycle, and the terms you will use throughout this section.
Who this section is for
Business owners, C-level leaders, product, engineering, and compliance teams. Read this page first to understand how Onboarding-as-a-Service works as a building block — how it lets your platform extend PayMongo to your own users so you can grow your ecosystem without rebuilding KYC, KYB, or payments yourself.
Overview
Onboarding-as-a-Service is the foundation building block for building your platforms on PayMongo. Use it to create accounts for the users in your ecosystem — merchants, sellers, riders, freelancers, consumers — and link them to your platform as child accounts. Once activated, each child can use the full PayMongo product suite the same way a stand-alone account would.
ScopeThis section is the developer guide for the Create an account path. The Invite path's mechanics (linking-request lifecycle, by-email and by-Account-ID flows) live in the canonical Linked accounts page. The concepts on this page apply to both paths.
How the model fits together
Creating a child account automatically links it to your platform as a child account. It goes through the same compliance work any other PayMongo account does — KYC for the authorized representative, KYB for the business when the child is a merchant. The flow is flexible: most platforms use PayMongo's standard identity verification, while approved partners with their own KYC (and, for merchants, KYB) capability can use Partner Verification to submit their own results.
Onboarding-as-a-Service covers the lifecycle from account creation to activation. Once activated, the child operates as a regular PayMongo account, and your platform can transact on its behalf through Linked transactions.
Coming soon — multi-association linked accounts + policy contractsThe linking model is moving from "one parent per child" to multi-association: an account can hold many relationships at once, each one its own record (
mr_xxxx) with a parent role and a child role. Each relationship will be governed by an explicit policy contract that both parties agree to. The contract scopes what the parent may do on that specific relationship — for example, view only the payments it created, or manage every transfer. Accounts created directly withPOST /v2/accountsreceive a default set of permissions. See Policy contracts for the full model and Default behavior at relationship creation for the defaults.
Glossary
| Term | Definition |
|---|---|
| Parent account | The role an account plays as the initiator of a relationship — typically your platform. With multi-association (Coming soon), an account is parent only within a specific relationship, not globally. |
| Child account | The role an account plays as the recipient of a relationship. Identified by an org_* ID. Can be of type merchant or consumer. With multi-association (Coming soon), an account is child only within a specific relationship. |
Account type — merchant | A business account. Requires KYC of the authorized representative and KYB of the business. Shown as Merchant in the dashboard. |
Account type — consumer | An individual account. Requires KYC of the account holder. No KYB. Shown as Non-business in the dashboard. |
| Authorized representative | The natural person who owns or is authorized to act for the account. KYC is performed against this person. |
| KYC | Know Your Customer. Identity verification of the authorized representative. |
| KYB | Know Your Business. Business risk and document review for merchant accounts. |
| Onboarding path | One of two ways to bring a child onto your platform: Invite (invitation-led; the recipient creates or owns the account) or Create an account (API-led; the parent creates the account). See Onboarding paths. |
| Invitation | A linking request the parent sends as part of the Invite path. Identified by lr_xxxx. Moves through pending, accepted, or cancelled. |
| Identity verification | The KYC step that validates the authorized representative's selfie and government-issued ID. Required before activation unless Partner Verification is enabled for your platform. |
| Activation | The step that opens the child account for live transactions. Once activated, account details can no longer be edited through the API. |
| Activation status | The current state of the child account. See Activation statuses below. |
| Capability | A product the child account is enabled to use (QR Ph, wallets, cards, e-wallets, payouts). Lives on the child. See Account capabilities. |
| Linking request | The technical term for the invitation object created by the Invite path. Identified by lr_xxxx. Synonymous with Invitation. |
| Relationship (Coming soon) | A single linked-account record. One direction only — parent → child — identified by mr_xxxx. Each direction is its own record. See Policy contracts. |
| Policy contract (Coming soon) | The agreement attached to a relationship that scopes what the parent may do on that link. Authored by the parent, accepted by the child, amended mutually (Coming soon), terminable by either party. See Policy contracts. |
| Fully managed account | A child account the parent fully owns and operates, created with fully_managed: true on POST /v2/accounts. The parent gets full access to every resource on it, and all notifications go to the parent. Opt-in. See Fully managed accounts. |
| Linked transaction | A transaction created by a parent on behalf of an activated child, using the Account-ID header. Documented under Linked transactions. |
Key guide — capability and policy contract are differentCapability lives on the child account and determines which products the child can use. Policy contract (Coming soon) lives on the relationship and determines what the parent may do on that link. The parent's effective permissions on a link are the intersection of both. See Policy contracts for the full model.
Account lifecycle
flowchart LR A[Create account] --> B[Identity verification] B -->|passed| C[Activate account] B -->|failed| B C --> D[Activated] D -.->|may later be declined<br/>by post-activation review| E[Declined]
Activation is automatic once all requirements are in place. After activation, the child is also subject to a post-activation risk review by PayMongo. It is possible — though uncommon — for an account to be declined after activation as part of this review. If your account is declined post-activation, contact [email protected] to raise a dispute.
There are two retry points to design for during onboarding:
- Identity verification fails. Restart identity verification and submit another attempt. Repeat until the result is
passedbefore activating. - Activation reports missing fields. Update the missing fields, then call Activate again.
Activation statuses
The Accounts API uses these statuses:
| Status | Meaning |
|---|---|
pending | The child account exists but has not yet been activated. It cannot transact. |
activated | The child account is live and can use the products it has been provisioned with. |
declined | The child account is not allowed to transact. Activation was not granted, or the account was declined during post-activation review. |
For the general account-setup state machine across PayMongo (live Dashboard view), see Account setup.
What activation provisions
Activation follows the same default pattern as a normal PayMongo account. The defaults below apply to accounts in the Philippines.
| Child account type | Default capabilities at activation |
|---|---|
merchant | Wallet + QR Ph (P2M) as a payment-acceptance method, plus Dashboard access for the authorized representative |
consumer | Wallet (supports QR Ph (P2P) transfers; no payment-acceptance method is provisioned), plus Dashboard access for the authorized representative |
Additional payment methods and other products are not granted by default.
Coming soon
- Self-serve toggle dashboard access for child accounts — Disabling dashboard access currently requires creating a support request. Self-serve flow is coming soon (Q4 2026).
To request additional capabilities for a child, see Account capabilities.
Opt-in features
Some Onboarding-as-a-Service features are off by default. Each carries its own eligibility requirements and regulatory considerations and must be reviewed before PayMongo enables it for your platform. Each has its own dedicated page with the full criteria.
| Feature | What it does |
|---|---|
| Auto-configuration | Applies your agreed configuration (rates, fees, payouts, and more) to every child you create, on activation. Does not activate capabilities. |
| Partner Verification | Submit your own KYC results (plus KYB for merchants) for approved partners with licensed processes. |
| Account capabilities | Enable specific products on a child beyond the activation defaults. |
| Fully managed accounts | Create children your platform fully owns and operates, with all notifications sent to you. |
Related pages
- Onboarding paths — choose the right approach for your platform.
- Quick start — implement the end-to-end happy path.
- Onboarding webhooks — listen for identity verification and activation events.
- Linked accounts — the parent reference for parent / child relationships.
- Linked transactions — operate on a child after activation.
Updated about 1 month ago
