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 [email protected] 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.

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:

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.

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.

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.

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)