Introduction

The Accounts API allows you as a parent merchant to create and manage child accounts (merchants or consumers) under your platform. Once activated, child accounts can accept payments and access PayMongo's financial services on your behalf.

Definition of Terms

Parent Merchant

The primary merchant account that manages child merchants and their consumers. PayMongo interacts directly with the parent merchant to configure and oversee sub-accounts.

Child Accounts

A collective term for both child merchants and account related consumers that has a relationship established to a Parent merchant.

Before You Begin

Account Configuration Required

Before you can begin testing and integration, your account must be configured for the Platforms feature. Contact support@paymongo.com to request access.

All endpoints listed below support the use of test secret keys. Authenticating with a test key will return mock data, allowing you to safely verify the expected response structure and fields.

📘
Important: Once you have finished testing, switch to your live secret keys for the production environment. For more information, see the Authentication page.

Register a Webhook

Register a webhook to receive real-time notifications on child account lifecycle events. This is a one-time setup and applies to all child accounts onboarded under your platform.

Accounts Webhook — identity verification events
Onboarding Webhooks — account activation and decline events

Onboarding a Child Account

1. Create the Account

Create a child account with minimal data. Declare the account type at this step:

Merchant

A business accepting payments on your platform.

QRPH upon activation
More payment methods (coming soon)
Higher wallet limits

Consumer

An individual transacting on your platform.

Limited to QRPH upon activation
Standard wallet limit

See Create Account.

2. Complete Identity verification

Identity verification is required for a fully functional account. The authorized representative must provide legitimate government-issued ID and selfie — accounts are subject to review by PayMongo's risk engine and may be deactivated if details are found to be invalid.

Choose the flow that fits your integration:

Option 1 — Hosted Best if you do not have your own image capture capability. PayMongo returns a URL to a hosted microsite where the authorized representative completes a selfie and government ID capture.

See: Create Identity Verification Session

Option 2 — API Only Best if you already have image capture capability or hold the images. Submit the selfie and government ID files directly via API without redirecting the user.

See Create Identity Verification (API only flow).

Checking the verification result

After submitting identity verification, use Get Account to check the result before proceeding.

Scenario	Action
`identity_verification_status = "passed"`	No action required — proceed to the next step.
`identity_verification_status = "failed"`	Restart identity verification from this step for the user to retry.
Personal details do not match expected user details	Restart identity verification from this step for the user to retry.

3. Update the Account

Populate any remaining information on the child account. Some fields under the authorized representative are automatically pre-filled from the identity verification step. This endpoint can be called multiple times.

See Update Account.

4. Activate the Account

Once all requirements are fulfilled, activate the child account. Upon successful activation, QR Ph is automatically provisioned.

⚠️
Note: Once the account is activated, account details can no longer be edited. Ensure all information is accurate before proceeding.

If any required fields are missing, the API returns an error identifying the incomplete items.

See Activate Account.

5. Receive Activation Result

Your registered webhook receives the account.activated event once the child account is live and ready to transact.

Required Information for Activation

All fields in the Update Account endpoint are optional to support saving progress across multiple calls. However, the following must be complete before calling Activate Account.

📘
After identity verification is completed, some fields are automatically pre-filled from the captured ID. Review and supply any remaining fields before activating.

Person (all account types)

Full name and date of birth
Nationality and place of birth
Mobile number and email address
Nature of work and source of funds
Tax Identification Number (TIN)
Current address

Business (type=merchant only)

Trade name
Business address
Industry and description
Business age, size, and estimated monthly transaction volume
Tax Identification Number (TIN)

📘
Business documents (e.g. SEC/DTI certificates) are not required at this stage. They are only needed when upgrading to additional payment methods beyond QR Ph.