Who this section is for

Engineering and product teams in platform building businesses, who need the whole Onboarding-as-a-Service integration in one view before building it stage by stage.

Overview

Onboarding-as-a-Service takes a platform from creating a linked account to processing payments or wallet transactions on it, all through API with the platform's own secret key. This page shows the four stages in order and links to the page that owns each one.

📘
Replaces the legacy Onboarding API
This flow fully replaces the legacy Onboarding API. The legacy API receives no new features and will be removed on January 1, 2027. Platforms still on it should move to the flow below before then.

⚠️
Child API keys are no longer shared
Accounts created with the Accounts API do not return child API keys, in the API response or in webhooks. To act on a linked account, use your own secret key with the Account-ID header (Linked Transactions). The legacy Onboarding API still sends child API keys in its activation webhooks until it is removed on January 1, 2027. If your integration stores or uses child keys, move it to Linked Transactions before then.

The four stages

Stage	What it does	Applies to
Account creation	Create, verify, and activate a linked account	Merchants and consumers
Linked Transactions	Process payments or wallet transactions on the account with your own key	Merchants and consumers
Capability requests	Update the business profile and add payment methods or other capabilities	Mostly merchants
Negative paths	Recover from failed verification, clarification requests, and declines	Merchants and consumers

Every call uses your parent secret key. Calls that act on a linked account add Account-ID: org_{child_id}.

1. Account creation

Create the account, register its webhook, verify the account holder, complete the details, and activate.

Create the account. POST /v2/accounts with type set to merchant or consumer. Store the returned org_… ID. To own and operate the account fully, including all notifications, send fully_managed: true (an opt-in; see Fully managed accounts).
Register the child webhook. POST /v1/webhooks with Account-ID, right after creation. Capability request and transaction events are delivered only to the linked account, so this webhook is how you receive them.
Verify identity. Use the hosted flow or submit images by API. Verification you trigger is reported on your own (parent) webhook.
Update details. PATCH /v2/accounts/{id} with the remaining person details, and business details for merchants.
Activate. POST /v2/accounts/{id}/activate. The outcome arrives as merchant.activated / merchant.declined or consumer.activated / consumer.declined.

At activation, merchants receive a wallet and QR Ph (P2M); consumers receive a wallet.

Read next: Quick start · Key concepts · Onboarding webhooks · Best practices · Testing

2. Linked Transactions

Once the account is active, process on it with your own secret key and the Account-ID header. Records are created on the linked account, funds settle to it, and its events go to the child webhook from stage 1.

Merchants: accept payments with Checkout Sessions or Payment Intents, refund, and reconcile.
Consumers: operate the wallet, such as transfers and QR Ph (P2P).

Only capabilities enabled on the account work. A method that is not enabled returns payment_method_not_allowed; add it in stage 3.

Read next: Linked Transactions (supported resources and errors) · Linked accounts

3. Capability requests

Add what activation does not provide, such as cards and e-wallets, or update the business profile, by sending capability requests for the linked account through the Capability Requests API. A parent can send them only for an account it fully manages. For any other linked account, the call returns 403 with accountid_operation_not_granted, and the account requests its own capabilities.

Update the business profile first if needed. An account update request (prd_svc_paymongo_account_update) changes business details after activation, including upgrading business_type from individual. Registered business documents are attached to the request.
Check eligibility. GET /v1/requests/eligibility/{product_code} lists anything missing.
Request each capability. One request per product code.
Wait for the outcome. Each request is reviewed by PayMongo. Its capability_request.* events arrive on the child webhook; act on capability_request.completed and handle clarification and decline (stage 4).

Consumers rarely need this stage. Their wallet request is created and handled by PayMongo at activation.

Read next: Capability requests (account update, attaching documents) · Capability request webhooks · Account capabilities (catalog) (eligibility by business type) · Auto-configuration

4. Negative paths

Most rejections are recoverable, and each arrives as a webhook. Design for them before launch, since they are the paths that run at scale.

Situation	Signal	What to do
Verification fails or is invalid	`account.identity_verification.failed`	Show `failure_reason`, start a new verification session
Verification session expired	Session older than 72 hours	Start a new session
Account activated after failed verification	Wallet in closed-loop mode, wallet request under review	Wait for the review, or a clarification request
Reviewer needs more information	`capability_request.pending_clarification` with `merchant_note`	Show the note, collect what is asked, and respond as described in Troubleshooting
Capability request declined	`capability_request.declined`	Show the reason; resolve before opening a new request
Account declined	`merchant.declined`, `consumer.declined`	The decline is final for that account; see Troubleshooting for next steps

Rules that apply to every handler: verify signatures, show reviewer notes but never branch on their wording, and be idempotent on the event id, since clarification can repeat with the same event type.