Who this section is for

Developers who have chosen the Create an account onboarding path and are ready to integrate. This page walks through the full Accounts API flow with the minimum payloads needed to reach activation.

Before you begin

Overview

The happy path has five calls. The steps are the same for both account types — what differs is the data you collect.

flowchart LR
  A[1 Create] --> B[2 Identity verification]
  B -->|passed| C[3 Update]
  C --> D[4 Activate]
  D --> E[5 Listen for webhook]

Merchant vs consumer at a glance

Both types go through the same five steps below. Step 1 sets the type; Step 3 collects the fields that match it; Step 4 provisions the capabilities listed above.

1. Create the child account

Create the account with the minimum required data. Declare the type here — it cannot be changed later.

curl --request POST \
     --url https://api.paymongo.com/v2/accounts \
     --header 'Content-Type: application/json' \
     --header 'authorization: Basic <base64-encoded-sk_parent_key>' \
     --data '{
       "type": "merchant",
       "person": {
         "email_address": "[email protected]",
         "mobile_number": "+639991234567"
       }
     }'

curl --request POST \
     --url https://api.paymongo.com/v2/accounts \
     --header 'Content-Type: application/json' \
     --header 'authorization: Basic <base64-encoded-sk_parent_key>' \
     --data '{
       "type": "consumer",
       "person": {
         "email_address": "[email protected]",
         "mobile_number": "+639991234567"
       }
     }'

A successful call returns the new child account with activation_status: "pending" and a generated id (prefixed org_). Save this id — every subsequent call refers to it.

{
  "data": {
    "id": "org_zeZdrgooHpjxzDpwvAsHXEAr",
    "type": "merchant",
    "activation_status": "pending",
    "person": {
      "type": "representative",
      "email_address": "[email protected]",
      "mobile_number": "+639991234567",
      "identity_verification_status": "pending"
    },
    "created_at": 1680000000,
    "updated_at": 1680000000
  }
}

See the full schema in Account resource and the request reference in Create account.

2. Run identity verification

Identity verification confirms the authorized representative is who they claim to be. You have three options:

If you are using Partner Verification, follow that path instead of the API calls below. See Partner Verification for the full process — both eligibility and the submission API.

Option A — Hosted identity verification

PayMongo returns a URL to a hosted microsite where the representative completes capture.

curl --request POST \
     --url https://api.paymongo.com/v2/accounts/org_zeZdrgooHpjxzDpwvAsHXEAr/identity_verification \
     --header 'authorization: Basic <base64-encoded-sk_parent_key>'

{
  "data": {
    "id": "verif_example_session",
    "type": "identity_verification",
    "attributes": {
      "status": "pending",
      "hosted_url": "https://identity.paymongo.com/v/verif_example_session",
      "expired_at": "2026-06-05T01:34:50Z"
    }
  }
}

Send hosted_url to the representative. Verification sessions expire 72 hours after creation — generate a new session if it expires.

Option B — API-only identity verification

Submit the selfie and government ID directly without redirecting the user.

curl --request POST \
     --url https://api.paymongo.com/v2/accounts/org_zeZdrgooHpjxzDpwvAsHXEAr/identity_verification/api \
     --header 'Content-Type: application/json' \
     --header 'authorization: Basic <base64-encoded-sk_parent_key>' \
     --data '{
       "document_type": "national_id_ph",
       "front_image_url": "https://your-cdn.example/front.jpg",
       "back_image_url": "https://your-cdn.example/back.jpg",
       "selfie_image_url": "https://your-cdn.example/selfie.jpg"
     }'

When you submit a secondary document type, also include secondary_document_type referring to a different secondary document. See the Appendix for primary and secondary lists.

Option C — Partner Verification

See the dedicated Partner Verification page for eligibility, the submission API, and the resulting account state. The page also covers when Partner Verification replaces step 2 entirely.

Watch for the result

PayMongo emits a webhook the moment identity verification completes:

• account.identity_verification.passed → proceed to step 3.
• account.identity_verification.failed → start a new identity verification session and retry.

Webhook payloads are documented in Onboarding webhooks. If you do not use webhooks, poll Get account and check person.identity_verification_status.

Handling repeated failures

If a representative fails identity verification three times in a row using Option A or B, do not loop indefinitely. Proceed to activation with the account in identity_verification_status: failed. PayMongo automatically pools these for manual review by the onboarding team.

Initial state. The account becomes activated with a closed-loop wallet (limited capabilities). The user can transact within those limits while waiting.

Manual review SLA. 7–14 business days.

Possible outcomes

Where the retry happens

Communicate the interim state and the possible retry to your user before they hand off control.

3. Update remaining details

After identity verification passes, some fields are pre-filled from the captured ID (name, date of birth, address from the ID). Fill in the rest before activating.

curl --request PATCH \
     --url https://api.paymongo.com/v2/accounts/org_zeZdrgooHpjxzDpwvAsHXEAr \
     --header 'Content-Type: application/json' \
     --header 'authorization: Basic <base64-encoded-sk_parent_key>' \
     --data '{
       "person": {
         "nationality": "PHL",
         "place_of_birth": { "city": "Manila", "country": "PH" },
         "nature_of_work": "self_employed",
         "source_of_funds": "other",
         "source_of_funds_other": "ABC Trading",
         "tin": "123-456-789"
       },
       "business": {
         "trade_name": "ABC Store",
         "type": "sole_proprietor",
         "industry": "5732",
         "description": "Electronics retail",
         "age": "between_1_and_2_years",
         "size": "less_than_10",
         "estimated_monthly_volume": "between_100K_and_300K",
         "tin": "123-456-789-000",
         "address": {
           "line1": "456 Business Ave",
           "city": "Makati",
           "state": "PH-MNL",
           "country": "PH",
           "postal_code": "1234"
         }
       }
     }'

Update can be called multiple times. Non-required fields you omit are ignored. See the full field list in Update account and accepted enum values in the Appendix.

What you must supply before activation

Person — every account type

• 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 — merchant accounts only

• Trade name and business type
• Business address
• Industry (Merchant Category Code) and description
• Business age, size, and estimated monthly volume
• Tax Identification Number (TIN)

4. Activate the account

Once everything is in place, activate.

curl --request POST \
     --url https://api.paymongo.com/v2/accounts/org_zeZdrgooHpjxzDpwvAsHXEAr/activate \
     --header 'authorization: Basic <base64-encoded-sk_parent_key>'

If any required fields are missing, the response lists them by JSON pointer. Call Update account to supply them, then call Activate again.

{
  "errors": [
    {
      "code": "parameter_required",
      "detail": "business.industry is required for activation.",
      "source": { "pointer": "business.industry" }
    }
  ]
}

On success, the child enters activated status. Default capabilities depend on the account type:

• merchant — wallet plus QR Ph (P2M) as a payment-acceptance method.
• consumer — wallet only. The wallet supports QR Ph (P2P) for peer-to-peer transfers, but no payment-acceptance method is provisioned on a consumer account.

Other capabilities are granted on request — see Account capabilities.

Recipient Dashboard access

Activation also lets the child's authorized representative sign in to their own PayMongo Dashboard for that account. This is on by default.

Nothing happens automatically: PayMongo does not create a Dashboard user and does not email the representative. To sign in, the representative goes to PayMongo's Dashboard login page themselves and enters the email address you recorded on the account; PayMongo then emails them a sign-in code.

Your platform keeps its own access either way. If your product needs the recipient never to see PayMongo, dashboard access can be disabled for your child accounts — see Disable dashboard access

5. Listen for the activation webhook

Your registered webhook endpoint receives one of:

• merchant.activated — the child is live.
• merchant.declined — risk review declined the account.
• consumer.activated or consumer.declined — same for consumer accounts.

Use these events to mark the child as ready in your own system. Full payload examples and field references are in Onboarding webhooks.

{
  "data": {
    "id": "evt_example",
    "type": "event",
    "attributes": {
      "type": "merchant.activated",
      "data": {
        "merchant_id": "org_zeZdrgooHpjxzDpwvAsHXEAr",
        "activation_status": "activated",
        "features": ["qrph"]
      }
    }
  }
}

What's next